@herbertgao/pi-extensions 2026.8.3 → 2026.8.4

package/node_modules/pi-footer/src/ui/global-menu.ts

@@ -0,0 +1,126 @@
+import type { ColorName } from "../colors.js";
+import {
+  ansi256Digits,
+  appendAnsi256Digit,
+  colorDisplayName,
+  deleteAnsi256Digit,
+  STANDARD_COLORS,
+} from "../colors.js";
+import { cloneConfig, configWithPreset, DEFAULT_CONFIG } from "../config.js";
+import { PRESET_DEFINITIONS, type Preset } from "../presets.js";
+import { SEPARATOR_VALUES } from "../separators.js";
+import type { StatuslineConfig, StatuslineSettings } from "../types.js";
+import { ICON_MODE_VALUES } from "../types.js";
+import { adjustAnsi, cycle } from "./helpers.js";
+import { ICON_MODE_LABELS } from "./model.js";
+
+export const GLOBAL_MENU_ACTIONS = [
+  "toggle-enabled",
+  "preset",
+  "separator",
+  "separator-fg",
+  "separator-bg",
+  "separator-fg-ansi",
+  "separator-bg-ansi",
+  "icon-mode",
+  "minimalist",
+  "reset",
+] as const;
+
+type GlobalMenuAction = (typeof GLOBAL_MENU_ACTIONS)[number];
+
+export const GLOBAL_MENU_HINT =
+  "↑/↓ option • ←/→ or enter change • type digits for ANSI256 • backspace delete • esc back";
+
+export function globalMenuFields(config: StatuslineSettings): string[] {
+  return [
+    `Enabled: ${config.enabled ? "on" : "off"}`,
+    `Preset: ${config.preset}`,
+    `Separator: ${config.separator}`,
+    `Separator foreground: ${colorDisplayName(config.separatorFg)}`,
+    `Separator background: ${colorDisplayName(config.separatorBg)}`,
+    `Custom ANSI256 separator foreground: ${ansi256Digits(config.separatorFg)}`,
+    `Custom ANSI256 separator background: ${ansi256Digits(config.separatorBg)}`,
+    `Icons: ${ICON_MODE_LABELS[config.iconMode]}`,
+    `Minimalist mode: ${config.minimalist ? "on" : "off"}`,
+    "Reset to defaults",
+  ];
+}
+
+export function globalMenuAction(index: number): GlobalMenuAction {
+  return GLOBAL_MENU_ACTIONS[index] ?? "reset";
+}
+
+export function applyGlobalMenuAction(
+  config: StatuslineConfig,
+  action: GlobalMenuAction,
+  delta: number,
+): StatuslineConfig {
+  if (action === "preset")
+    return configWithPreset(
+      config,
+      cycle(Object.keys(PRESET_DEFINITIONS) as Preset[], config.preset, delta),
+    );
+  if (action === "reset") return cloneConfig(DEFAULT_CONFIG);
+
+  const next = { ...config };
+  applyGlobalSettingsAction(next, action, delta);
+  return next;
+}
+
+export function applyGlobalSettingsAction(
+  settings: StatuslineSettings,
+  action: GlobalMenuAction,
+  delta: number,
+): boolean {
+  if (action === "toggle-enabled") settings.enabled = !settings.enabled;
+  else if (action === "separator")
+    settings.separator = cycle(SEPARATOR_VALUES, settings.separator, delta);
+  else if (action === "separator-fg")
+    settings.separatorFg = cycleStandardColor(settings.separatorFg, delta);
+  else if (action === "separator-bg")
+    settings.separatorBg = cycleStandardColor(settings.separatorBg, delta);
+  else if (action === "separator-fg-ansi")
+    settings.separatorFg = adjustAnsi(settings.separatorFg, delta);
+  else if (action === "separator-bg-ansi")
+    settings.separatorBg = adjustAnsi(settings.separatorBg, delta);
+  else if (action === "icon-mode")
+    settings.iconMode = cycle(ICON_MODE_VALUES, settings.iconMode, delta);
+  else if (action === "minimalist") settings.minimalist = !settings.minimalist;
+  else return false;
+  return true;
+}
+
+export function applyGlobalSettingsTextInput(
+  settings: StatuslineSettings,
+  action: GlobalMenuAction,
+  data: string,
+): boolean {
+  if (!/^\d$/.test(data)) return false;
+  if (action === "separator-fg-ansi")
+    settings.separatorFg = appendAnsi256Digit(settings.separatorFg, data);
+  else if (action === "separator-bg-ansi")
+    settings.separatorBg = appendAnsi256Digit(settings.separatorBg, data);
+  else return false;
+  return true;
+}
+
+export function applyGlobalSettingsBackspace(
+  settings: StatuslineSettings,
+  action: GlobalMenuAction,
+): boolean {
+  if (action === "separator-fg-ansi")
+    settings.separatorFg = deleteAnsi256Digit(settings.separatorFg);
+  else if (action === "separator-bg-ansi")
+    settings.separatorBg = deleteAnsi256Digit(settings.separatorBg);
+  else return false;
+  return true;
+}
+
+function cycleStandardColor(current: ColorName, delta: number): ColorName {
+  return cycle(
+    STANDARD_COLORS.map((color) => color.value),
+    current,
+    delta,
+  );
+}

package/node_modules/pi-footer/src/ui/helpers.ts

@@ -0,0 +1,44 @@
+import type { ColorName } from "../colors.js";
+import type { ScreenView } from "./model.js";
+
+export function escapeTarget(view: ScreenView): ScreenView | "close" {
+  if (view === "main") return "close";
+  if (
+    view === "line-list" ||
+    view === "color-line-list" ||
+    view === "terminal" ||
+    view === "global" ||
+    view === "extension-status-row"
+  )
+    return "main";
+  if (view === "widget-list") return "line-list";
+  if (view === "color-widget-list") return "color-line-list";
+  if (view === "edit-colors") return "color-widget-list";
+  if (view === "add-widget" || view === "edit-widget") return "widget-list";
+  if (view === "confirm-color-level") return "terminal";
+  if (view === "confirm-exit") return "main";
+  return "main";
+}
+
+export function cycle<T>(values: readonly T[], current: T, delta: number): T {
+  const index = values.indexOf(current);
+  return values[(index + delta + values.length) % values.length] ?? current;
+}
+
+export function adjustAnsi(current: ColorName | undefined, delta: number): ColorName {
+  const currentCode = current?.startsWith("ansi256:") ? Number(current.slice(8)) : 0;
+  return `ansi256:${wrap(currentCode + delta, 256)}` as ColorName;
+}
+
+export function wrap(value: number, length: number): number {
+  if (length <= 0) return 0;
+  return (value + length) % length;
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+export function isPrintable(data: string): boolean {
+  return data.length === 1 && data.charCodeAt(0) >= 32 && data.charCodeAt(0) !== 127;
+}

package/node_modules/pi-footer/src/ui/layout.ts

@@ -0,0 +1,17 @@
+export const CONFIG_UI_RESERVED_ROWS = 8;
+export const MIN_VISIBLE_ROW_COUNT = 4;
+
+export function activeLineCount(lines: readonly (readonly unknown[])[]): number {
+  return lines.filter((line) => line.length > 0).length;
+}
+
+export function visibleRowCount(
+  terminalRows: number,
+  heightRatio: number,
+  activeLines: number,
+): number {
+  return Math.max(
+    MIN_VISIBLE_ROW_COUNT,
+    Math.floor(terminalRows * heightRatio) - CONFIG_UI_RESERVED_ROWS - activeLines,
+  );
+}

package/node_modules/pi-footer/src/ui/line-list.ts

@@ -0,0 +1,19 @@
+export const LINE_LIST_HINT =
+  "↑/↓ select • pgup/pgdn jump • enter edit • a add • c clone • w/s move • d delete • esc back";
+
+export function lineListCountLabel(total: number, start: number, end: number): string {
+  return `${total} line(s), showing ${rangeLabel(start, end, total)}`;
+}
+
+export function lineListItemLabel(
+  index: number,
+  widgetCount: number,
+  dim: (text: string) => string,
+): string {
+  return `☰ Line ${index + 1} ${dim(`(${widgetCount} widget${widgetCount === 1 ? "" : "s"})`)}`;
+}
+
+function rangeLabel(start: number, end: number, total: number): string {
+  if (total === 0) return "0-0";
+  return `${start + 1}-${end}`;
+}

package/node_modules/pi-footer/src/ui/model.ts

@@ -0,0 +1,64 @@
+import type { ColorLevel } from "../colors.js";
+import type { IconMode, TerminalWidthMode } from "../types.js";
+import type { WidgetProperty } from "../widgets/types.js";
+
+export const CONFIG_UI_HEIGHT_RATIO = 1;
+
+export const WIDTH_MODE_LABELS: Record<TerminalWidthMode, string> = {
+  full: "Full width always",
+  "full-minus-40": "Full width minus 40",
+};
+
+export const COLOR_LEVEL_LABELS: Record<ColorLevel, string> = {
+  truecolor: "Truecolor",
+  ansi256: "256 Color",
+  ansi16: "Basic (Standard 16-color)",
+  none: "No Color",
+};
+
+export const ICON_MODE_LABELS: Record<IconMode, string> = {
+  emoji: "Emoji",
+  nerd: "Nerd Font icons",
+  text: "Text labels",
+};
+
+export type ScreenView =
+  | "main"
+  | "line-list"
+  | "widget-list"
+  | "add-widget"
+  | "edit-widget"
+  | "color-line-list"
+  | "color-widget-list"
+  | "edit-colors"
+  | "terminal"
+  | "confirm-color-level"
+  | "confirm-exit"
+  | "global"
+  | "extension-status-row";
+
+type ColorField =
+  | "fg"
+  | "bg"
+  | "bold"
+  | "fgAnsi"
+  | "bgAnsi"
+  | "warningFg"
+  | "warningBg"
+  | "warningFgAnsi"
+  | "warningBgAnsi"
+  | "dangerFg"
+  | "dangerBg"
+  | "dangerFgAnsi"
+  | "dangerBgAnsi";
+
+// Flattened, UI-facing projection of WidgetProperty: id/label/kind plus the editable bits
+// hoisted out of WidgetProperty.options. Derived structurally so it can't drift from the source.
+export type OptionField = Pick<WidgetProperty, "id" | "label" | "kind"> &
+  Pick<NonNullable<WidgetProperty["options"]>, "min" | "max" | "choices" | "editAction">;
+
+export interface ColorOptionField {
+  id: ColorField;
+  label: string;
+  kind: "color" | "boolean" | "ansi";
+}

package/node_modules/pi-footer/src/ui/navigation.ts

@@ -0,0 +1,29 @@
+import { clamp } from "./helpers.js";
+
+export function pageSelection(
+  selected: number,
+  total: number,
+  visibleCount: number,
+  direction: -1 | 1,
+): number {
+  if (total <= 0) return 0;
+  return clamp(selected + direction * visibleCount, 0, total - 1);
+}
+
+export function scrollWindow(
+  total: number,
+  selected: number,
+  visibleCount: number,
+): { start: number; end: number } {
+  const start = clamp(
+    selected - Math.floor(visibleCount / 2),
+    0,
+    Math.max(0, total - visibleCount),
+  );
+  return { start, end: Math.min(total, start + visibleCount) };
+}
+
+export function rangeLabel(start: number, end: number, total: number): string {
+  if (total === 0) return "0-0";
+  return `${start + 1}-${end}`;
+}

package/node_modules/pi-footer/src/ui/option-edit.ts

@@ -0,0 +1,93 @@
+import { registry } from "../widgets/registry.js";
+import type { Widget, WidgetEditAction, WidgetProperty } from "../widgets/types.js";
+import { getBooleanField, getNumberField, getTextField } from "./fields.js";
+import { cycle } from "./helpers.js";
+import type { OptionField } from "./model.js";
+
+type OptionFieldApplyResult = "changed" | "unchanged" | WidgetEditAction;
+
+type OptionFieldEdit = { kind: "appendText"; text: string } | { kind: "deleteText" };
+
+export function applyOptionFieldEdit(
+  widget: Widget,
+  field: OptionField,
+  edit: OptionFieldEdit,
+): OptionFieldApplyResult {
+  if (field.kind !== "text") return "unchanged";
+  if (edit.kind === "appendText") {
+    widget.update({ [field.id]: getTextField(widget, field.id) + edit.text });
+    return "changed";
+  }
+  widget.update({ [field.id]: getTextField(widget, field.id).slice(0, -1) });
+  return "changed";
+}
+
+export function applyOptionField(
+  widget: Widget,
+  field: OptionField,
+  delta: number,
+): OptionFieldApplyResult {
+  if (field.id === "enabled") {
+    widget.toggle();
+    return "changed";
+  }
+  if (field.editAction) return field.editAction;
+
+  const properties: readonly WidgetProperty[] = registry.spec(widget.type).properties;
+  const property = properties.find((item) => item.id === field.id);
+  if (property?.options?.editAction) return property.options.editAction;
+
+  if (field.kind === "boolean" && isMetadataBooleanField(widget, field.id)) {
+    metadataSetBooleanField(widget, field.id, !getBooleanField(widget, field.id));
+    return "changed";
+  }
+  if (field.kind === "number") {
+    if (property?.kind !== "number") return "unchanged";
+    const min = field.min ?? property.options?.min ?? 1;
+    const max = field.max ?? property.options?.max ?? 99;
+    const current = getNumberField(widget, field.id) ?? min;
+    metadataSetNumberField(widget, field.id, Math.min(max, Math.max(min, current + delta)));
+    return "changed";
+  }
+  if (field.kind === "choice") {
+    if (property?.kind !== "choice") return "unchanged";
+    const choices = field.choices ?? property.options?.choices;
+    const choiceIds = choices?.map((choice) => choice.id) ?? [];
+    if (choiceIds.length === 0) return "unchanged";
+    const current = getTextField(widget, field.id) || (choiceIds[0] ?? "");
+    widget.update({ [field.id]: cycle(choiceIds, current, delta) });
+    return "changed";
+  }
+  return "unchanged";
+}
+
+function metadataSetBooleanField(widget: Widget, id: string, value: boolean): void {
+  const spec = registry.spec(widget.type);
+  const properties: readonly WidgetProperty[] = spec.properties;
+  const property = properties.find((item) => item.id === id);
+  if (property?.kind === "boolean") {
+    widget.update({ [id]: value });
+    return;
+  }
+  if (!spec.baseOptions.some((option) => option === id)) return;
+  if (id === "raw") widget.update({ raw: value });
+  if (id === "hideWhenEmpty") widget.update({ hideWhenEmpty: value });
+  if (id === "hideWhenZero") widget.update({ hideWhenZero: value });
+}
+
+function metadataSetNumberField(widget: Widget, id: string, value: number): void {
+  const properties: readonly WidgetProperty[] = registry.spec(widget.type).properties;
+  const property = properties.find((item) => item.id === id);
+  if (property?.kind === "number") widget.update({ [id]: value });
+}
+
+function isMetadataBooleanField(widget: Widget, id: string): boolean {
+  const spec = registry.spec(widget.type);
+  const properties: readonly WidgetProperty[] = spec.properties;
+  const property = properties.find((item) => item.id === id);
+  if (property?.kind === "boolean") return true;
+  return (
+    spec.baseOptions.some((option) => option === id) &&
+    (id === "raw" || id === "hideWhenEmpty" || id === "hideWhenZero")
+  );
+}

package/node_modules/pi-footer/src/ui/overlay-render.ts

@@ -0,0 +1,103 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import type { GetExtensionStatuses } from "../extension-statuses.js";
+import { renderStatuslines } from "../render.js";
+import type { StatuslineData } from "../types.js";
+import type { WidgetStore } from "../widgets/store.js";
+import type { ScreenRender } from "./screen-render.js";
+import type { UiTheme } from "./theme.js";
+import { configTitleBarParts, previewTitleParts } from "./title-bar.js";
+
+interface OverlayRenderOptions {
+  width: number;
+  terminalRows: number;
+  activeLineCount: number;
+  visibleRowCount: number;
+  store: WidgetStore;
+  previewData: StatuslineData;
+  getExtensionStatuses: GetExtensionStatuses;
+  theme: Theme;
+  requestRender?: () => void;
+  configStateText: string;
+  body: string[];
+}
+
+interface OverlayLayout {
+  innerWidth: number;
+}
+
+export class OverlayRender {
+  constructor(
+    private readonly theme: UiTheme,
+    private readonly screenRender: ScreenRender,
+  ) {}
+
+  render(options: OverlayRenderOptions): string[] {
+    const layout = this.layout(options);
+    const lines = [
+      this.previewTitleLine(layout),
+      ...this.previewLines(options),
+      this.previewBottomLine(layout),
+      this.blankSeparator(options.width),
+      this.configTitleLine(options, layout),
+      ...options.body,
+    ];
+
+    this.fillToTerminal(lines, options);
+    lines.push(this.bottomBorder(layout));
+    return lines;
+  }
+
+  private layout(options: OverlayRenderOptions): OverlayLayout {
+    return { innerWidth: Math.max(1, options.width - 2) };
+  }
+
+  private previewTitleLine(layout: OverlayLayout): string {
+    const previewTitle = previewTitleParts(layout.innerWidth);
+    return (
+      this.theme.border("─") +
+      this.theme.previewTitle(previewTitle.title) +
+      this.theme.border(`${"─".repeat(previewTitle.rightPad)}─`)
+    );
+  }
+
+  private previewLines(options: OverlayRenderOptions): string[] {
+    return renderStatuslines(options.store, options.previewData, Math.max(20, options.width), {
+      getExtensionStatuses: options.getExtensionStatuses,
+      theme: options.theme,
+      ...(options.requestRender ? { requestRender: options.requestRender } : {}),
+    }).map((line) => this.screenRender.lineW(line, options.width));
+  }
+
+  private previewBottomLine(layout: OverlayLayout): string {
+    return this.theme.border(`─${"─".repeat(layout.innerWidth)}─`);
+  }
+
+  private blankSeparator(width: number): string {
+    return " " + this.screenRender.padLine(width, "", "") + " ";
+  }
+
+  private configTitleLine(options: OverlayRenderOptions, layout: OverlayLayout): string {
+    const title = configTitleBarParts(
+      layout.innerWidth,
+      (text) => this.theme.dim(text),
+      Date.now(),
+      options.configStateText,
+      (text) => this.theme.border(text),
+    );
+    return (
+      this.theme.border("╭─") + title.title + this.theme.border(`${"─".repeat(title.rightPad)}╮`)
+    );
+  }
+
+  private fillToTerminal(lines: string[], options: OverlayRenderOptions): void {
+    const neededToFillScreen = options.terminalRows - lines.length - 1;
+    if (neededToFillScreen > 0) {
+      lines.push(...Array(neededToFillScreen).fill(this.screenRender.line("", options.width)));
+    }
+  }
+
+  private bottomBorder(layout: OverlayLayout): string {
+    return this.theme.border(`╰${"─".repeat(layout.innerWidth)}╯`);
+  }
+}

package/node_modules/pi-footer/src/ui/screen-context.ts

@@ -0,0 +1,18 @@
+import type { GetExtensionStatuses } from "../extension-statuses.js";
+import type { Widget } from "../widgets/types.js";
+import type { ScreenView } from "./model.js";
+import type { ScreenState } from "./screen-state.js";
+import type { UiTheme } from "./theme.js";
+
+export interface ScreenContext {
+  state: ScreenState;
+  theme: UiTheme;
+  getExtensionStatuses: GetExtensionStatuses;
+  currentLine(): Widget[];
+  currentWidget(): Widget | undefined;
+  visibleRowCount(): number;
+  show(view: ScreenView): void;
+  emitChange(): void;
+  save(exitAfterSave: boolean): void;
+  exitWithoutSaving(): void;
+}

package/node_modules/pi-footer/src/ui/screen-controller.ts

@@ -0,0 +1,27 @@
+import type { ScreenContext } from "./screen-context.js";
+import type { ScreenView } from "./model.js";
+import type { Controller } from "./screens/controller.js";
+
+export class ScreenController {
+  private readonly screens = new Map<ScreenView, Controller>();
+
+  constructor(private readonly ctx: ScreenContext) {}
+
+  register(view: ScreenView, screen: Controller): void {
+    this.screens.set(view, screen);
+  }
+
+  renderScreen(width: number): string[] {
+    return this.currentScreen().renderScreen(width);
+  }
+
+  handleInput(data: string): void {
+    this.currentScreen().handleInput(data);
+  }
+
+  private currentScreen(): Controller {
+    const screen = this.screens.get(this.ctx.state.view);
+    if (!screen) throw new Error(`No screen registered for view: ${this.ctx.state.view}`);
+    return screen;
+  }
+}

package/node_modules/pi-footer/src/ui/screen-render.ts

@@ -0,0 +1,32 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import type { UiTheme } from "./theme.js";
+
+export class ScreenRender {
+  constructor(private readonly theme: UiTheme) {}
+
+  menuTitle(title: string, description = ""): string {
+    if (description.length === 0) return this.theme.accent(title);
+    return this.theme.success(`•${title}`) + " " + this.theme.dim(description);
+  }
+
+  padLine(width: number, content: string, ellipsis = "…"): string {
+    return truncateToWidth(content, Math.max(1, width - 2), ellipsis, true);
+  }
+
+  lineW(content: string, width: number): string {
+    // NOTE: uncoment below for demo-look preview.
+    // const clipped = truncateToWidth(content, Math.max(0, width - 2), "…");
+    const clipped = truncateToWidth(content, Math.max(0, width), "…");
+    return `${clipped}${" ".repeat(Math.max(0, width - visibleWidth(clipped)))}`;
+  }
+
+  line(content: string, width: number): string {
+    return this.theme.border("│") + this.padLine(width, content) + this.theme.border("│");
+  }
+
+  menuLine(selected: boolean, content: string, width: number): string {
+    const text = `${selected ? "›" : " "}  ${content}`;
+    return this.line(selected ? this.theme.selected(text) : text, width);
+  }
+}

package/node_modules/pi-footer/src/ui/screen-state.ts

@@ -0,0 +1,20 @@
+import type { WidgetStore } from "../widgets/store.js";
+import type { ScreenView } from "./model.js";
+
+export interface ScreenState {
+  store: WidgetStore;
+  view: ScreenView;
+  viewBeforeConfirmExit: ScreenView;
+  selectedLine: number;
+  selectedWidget: number;
+}
+
+export function createScreenState(store: WidgetStore): ScreenState {
+  return {
+    store,
+    view: "main",
+    viewBeforeConfirmExit: "main",
+    selectedLine: 0,
+    selectedWidget: 0,
+  };
+}