pi-incarnate-ui 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+- Preserve the public portion of Pi's default Footer semantics: assistant/tool/compaction/branch-summary usage, cache reads and writes, latest cache hit rate, session name, multi-provider labels, known Kimi subscription status, and context-pressure colors.
+- Add a real-entry integration gate against the sibling `pi-incarnate` workspace and run it in CI for both supported Node versions.
+- Remove the unused `claim-v1` event; startup synchronization uses request-state and state events only.
+- Prototype a standalone startup Header driven by the pi-incarnate UI protocol.
+- Replace the scrolling startup dashboard with a fixed custom Footer capped at six rows.
+- Generate a four-row portrait preview from the single sanitized avatar asset and collapse to three or two rows on constrained terminals.
+- Preserve essential Pi runtime, context, model, directory, branch, cost, and extension status information in the replacement Footer.
+- Add `/incarnate-ui` as a bounded, keyboard-dismissible overlay that shows every row of the active sanitized avatar.
+- Leave Pi's default Footer untouched when no character is active, avatar presentation is off, or no compatible core state has arrived; acquire and release the custom Footer dynamically as state changes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-incarnate-ui contributors
+
+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,48 @@
+# pi-incarnate-ui
+
+`pi-incarnate-ui` 是 [pi-incarnate](https://github.com/NandySun/pi-incarnate) 的可选固定终端界面。
+
+它使用 Pi 的公开 `setFooter()` API，把角色呈现和必要的 Pi 运行信息组合成固定底部区域：
+
+- 固定区域严格不超过 6 行，避免压缩对话和输入框。
+- 宽终端使用同一份头像自动生成 4 行纵向采样预览，旁边显示角色、mood、来源和表单状态；不要求额外维护缩略图。
+- 终端窄于 72 列或低于 20 行时，自动降级为 1 行角色状态加 2 行运行信息。
+- `off`、未启用角色或核心扩展没有响应时完全归还 Pi 默认 Footer，不占用空闲布局。
+- 保留工作目录、Git 分支、session 名称、输入/输出与缓存 token、缓存命中率、cost、上下文占用、模型、provider、thinking 和其他扩展状态。
+- Pi 默认启动 Header、对话、工具输出和输入框保持原样。
+- `/incarnate-ui` 可按需打开完整头像浮层，Enter、Esc 或 `q` 关闭；浮层关闭后返回原输入界面。
+
+当前工作区是尚未发布的 `0.1.0` 本地候选；在用户明确授权前不发布 npm。首版不处理与其他自定义 Footer 扩展的共存。
+
+## Development
+
+```bash
+npm install
+npm run release:check
+npm run test:companion
+pi --no-extensions \
+  -e /path/to/pi-incarnate/extensions/index.ts \
+  -e /path/to/pi-incarnate-ui/extensions/index.ts
+```
+
+`test:companion` 要求核心仓库位于同级目录 `/path/to/pi-incarnate`。它加载两个真实扩展入口，验证两种加载顺序、状态生命周期、未知协议版本和缺失另一端的降级。
+
+启动后通过 `/incarnate` 选择角色。核心扩展只管理人格、角色资源和安全清理；所有终端绘制均由本 UI 扩展负责。未加载 UI 时人格仍然生效，但不显示角色图。
+
+需要查看未经四行采样的完整头像时运行：
+
+```text
+/incarnate-ui
+```
+
+查看器只在 TUI 中打开临时居中浮层，使用核心已经清理并限制为最多 48×16 的头像数据，不读取角色目录，也不改变 Footer 模式。终端高度不足时可用 `↑` / `↓` 滚动查看全部头像行。
+
+## 当前边界
+
+- 只在 TUI 模式设置 Footer；RPC、JSON 和 print 模式不接管表现层。
+- 角色状态由版本化的 `pi.events` 协议传递，UI 不直接读取角色目录。
+- `compact` 使用 3 行布局；`auto` 和 `full` 在宽度足够时使用最多 6 行布局；`off` 或未激活状态不接管 Footer。
+- 四行头像是从完整资源自动采样的常驻预览，不等同于完整原图；完整内容由按需查看器提供。
+- 完整头像查看器是临时 overlay，不占用常驻布局；无活动头像或非 TUI 模式时只给出提示。
+- 当前角色状态仍由 pi-incarnate 按 session 管理；新会话默认关闭，需要重新选择角色，此时显示 Pi 自身的默认 Footer。
+- Pi 0.85.0 的公开扩展上下文不暴露通用订阅检测和 auto-compaction 开关；UI 只保留默认 Footer 可公开重建的信息，并沿用 Pi 对 `kimi-coding` 的已知订阅标记。其他 provider 的内部订阅状态与 auto-compaction 标记不显示。

package/SECURITY.md

@@ -0,0 +1,11 @@
+# Security
+
+Pi extensions run with the same permissions as Pi. Review extension source before loading it.
+
+`pi-incarnate-ui` does not read character cards or avatar files. It receives a bounded UI snapshot over Pi's in-process event bus. The companion `pi-incarnate` extension remains responsible for validating character paths, decoding UTF-8, filtering ANSI sequences, limiting avatar dimensions, and forcing terminal color resets.
+
+The Footer renderer bounds every output line to the available terminal width, emits at most six rows, and accepts at most 16 avatar lines and 48 visible avatar columns. Character and runtime metadata is stripped of terminal control sequences before display. Unknown protocol versions and structurally invalid payloads are ignored.
+
+The optional full-avatar overlay renders only the same bounded in-memory snapshot; it does not read files. Its title metadata is sanitized, its rows are clipped to the assigned overlay width, and it closes without changing character state.
+
+This extension replaces Pi's Footer only while a compatible active character requests visible presentation in TUI mode. It restores Pi's default Footer when the character is inactive or presentation is off, and never claims the Footer if no compatible core state arrives. It does not replace the startup Header, editor, transcript renderer, or tool UI. Other custom Footer extensions may replace it according to extension load order.

package/extensions/index.ts

@@ -0,0 +1,214 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ReadonlyFooterDataProvider,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+
+import { AvatarViewerComponent } from "../src/avatar-viewer.ts";
+import { renderFooter, type FooterSessionInfo, type FooterStyles } from "../src/layout.ts";
+import {
+  isIncarnateUiStateV1,
+  UI_REQUEST_STATE_EVENT,
+  UI_STATE_EVENT,
+  type IncarnateUiStateV1,
+} from "../src/protocol.ts";
+
+const inactiveState: IncarnateUiStateV1 = { version: 1, active: false, avatarMode: "auto" };
+
+function themeStyles(theme: Theme): FooterStyles {
+  return {
+    accent: (text) => theme.fg("accent", text),
+    muted: (text) => theme.fg("muted", text),
+    dim: (text) => theme.fg("dim", text),
+    text: (text) => theme.fg("text", text),
+    success: (text) => theme.fg("success", text),
+    warning: (text) => theme.fg("warning", text),
+    error: (text) => theme.fg("error", text),
+  };
+}
+
+function numberField(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+function sessionUsage(
+  context: ExtensionContext | undefined,
+): Pick<
+  FooterSessionInfo,
+  "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheWriteTokens" | "cacheHitPercent" | "cost"
+> {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheWriteTokens = 0;
+  let cacheHitPercent: number | undefined;
+  let cost = 0;
+  for (const entry of context?.sessionManager.getEntries() ?? []) {
+    const record = entry as unknown as Record<string, unknown>;
+    let usageValue: unknown;
+    let assistantUsage = false;
+    if (entry.type === "message") {
+      const message = record.message as Record<string, unknown> | undefined;
+      if (message?.role !== "assistant" && message?.role !== "toolResult") continue;
+      usageValue = message.usage;
+      assistantUsage = message.role === "assistant";
+    } else if (entry.type === "branch_summary" || entry.type === "compaction") {
+      usageValue = record.usage;
+    } else {
+      continue;
+    }
+    if (!usageValue || typeof usageValue !== "object") continue;
+    const usage = usageValue as Record<string, unknown>;
+    inputTokens += numberField(usage.input);
+    outputTokens += numberField(usage.output);
+    cacheReadTokens += numberField(usage.cacheRead);
+    cacheWriteTokens += numberField(usage.cacheWrite);
+    if (assistantUsage) {
+      const promptTokens = numberField(usage.input) + numberField(usage.cacheRead) + numberField(usage.cacheWrite);
+      if (promptTokens > 0) cacheHitPercent = (numberField(usage.cacheRead) / promptTokens) * 100;
+    }
+    const usageCost = usage.cost;
+    if (usageCost && typeof usageCost === "object") cost += numberField((usageCost as Record<string, unknown>).total);
+  }
+  return { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, cacheHitPercent, cost };
+}
+
+function sessionInfo(
+  context: ExtensionContext | undefined,
+  footerData: ReadonlyFooterDataProvider,
+  tui: TUI,
+): FooterSessionInfo {
+  const usage = context?.getContextUsage();
+  const model = context?.model;
+  return {
+    model: model?.id,
+    provider: model?.provider,
+    availableProviderCount: footerData.getAvailableProviderCount(),
+    supportsReasoning: model?.reasoning,
+    thinking: context?.thinkingLevel,
+    cwd: context?.cwd,
+    branch: footerData.getGitBranch(),
+    sessionName: context?.sessionManager.getSessionName(),
+    contextPercent: usage?.percent,
+    contextWindow: usage?.contextWindow ?? model?.contextWindow,
+    usingSubscription: model?.provider === "kimi-coding",
+    statuses: [...footerData.getExtensionStatuses().entries()]
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([, value]) => value),
+    terminalRows: tui.terminal.rows,
+    ...sessionUsage(context),
+  };
+}
+
+export default function incarnateUiExtension(pi: ExtensionAPI): void {
+  let state = inactiveState;
+  let context: ExtensionContext | undefined;
+  let tui: TUI | undefined;
+  let footerInstalled = false;
+
+  const requestRender = (): void => tui?.requestRender();
+  const requestState = (): void => {
+    pi.events.emit(UI_REQUEST_STATE_EVENT, { version: 1 });
+  };
+
+  const shouldInstallFooter = (): boolean => Boolean(state.active && state.character && state.avatarMode !== "off");
+
+  const installFooter = (): void => {
+    if (!context || context.mode !== "tui" || footerInstalled) return;
+    context.ui.setFooter((footerTui, theme, footerData) => {
+      tui = footerTui;
+      const unsubscribe = footerData.onBranchChange(requestRender);
+      return {
+        render(width: number): string[] {
+          return renderFooter(width, state, sessionInfo(context, footerData, footerTui), themeStyles(theme));
+        },
+        invalidate() {},
+        dispose() {
+          unsubscribe();
+          if (tui === footerTui) tui = undefined;
+        },
+      };
+    });
+    footerInstalled = true;
+  };
+
+  const syncFooter = (): void => {
+    if (!context || context.mode !== "tui") return;
+    if (shouldInstallFooter()) {
+      if (footerInstalled) requestRender();
+      else installFooter();
+      return;
+    }
+    if (!footerInstalled) return;
+    context.ui.setFooter(undefined);
+    footerInstalled = false;
+    tui = undefined;
+  };
+
+  pi.events.on(UI_STATE_EVENT, (payload) => {
+    if (!isIncarnateUiStateV1(payload)) return;
+    state = payload;
+    syncFooter();
+  });
+
+  pi.registerCommand("incarnate-ui", {
+    description: "Show the active character's full avatar",
+    handler: async (args, ctx) => {
+      const action = args.trim();
+      if (action && action !== "avatar") {
+        ctx.ui.notify("Usage: /incarnate-ui [avatar]", "error");
+        return;
+      }
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify("The full avatar viewer is available only in TUI mode", "warning");
+        return;
+      }
+      if (!state.active || !state.avatar?.lines.length) {
+        ctx.ui.notify("No active avatar. Enable a character and its avatar first.", "warning");
+        return;
+      }
+      await ctx.ui.custom<void>(
+        (overlayTui, theme, _keybindings, done) => new AvatarViewerComponent(state, theme, done, overlayTui),
+        {
+          overlay: true,
+          overlayOptions: {
+            anchor: "center",
+            width: Math.max(24, Math.min(54, state.avatar.width + 4)),
+            maxHeight: 20,
+            margin: 1,
+          },
+        },
+      );
+    },
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    if (footerInstalled && context?.mode === "tui") context.ui.setFooter(undefined);
+    footerInstalled = false;
+    tui = undefined;
+    state = inactiveState;
+    context = ctx;
+    if (ctx.mode !== "tui") return;
+    requestState();
+  });
+
+  pi.on("model_select", (_event, ctx) => {
+    context = ctx;
+    requestRender();
+  });
+
+  pi.on("thinking_level_select", (_event, ctx) => {
+    context = ctx;
+    requestRender();
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (ctx.mode === "tui" && footerInstalled) ctx.ui.setFooter(undefined);
+    footerInstalled = false;
+    tui = undefined;
+    context = undefined;
+    state = inactiveState;
+  });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "pi-incarnate-ui",
+  "version": "0.1.0",
+  "description": "A compact character-aware footer for pi-incarnate",
+  "author": "NandySun",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NandySun/pi-incarnate-ui.git"
+  },
+  "homepage": "https://github.com/NandySun/pi-incarnate-ui#readme",
+  "bugs": {
+    "url": "https://github.com/NandySun/pi-incarnate-ui/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-agent",
+    "pi-extension",
+    "pi-incarnate",
+    "tui",
+    "footer"
+  ],
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md",
+    "extensions",
+    "src"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --test tests/*.test.ts",
+    "test:companion": "npm --prefix ../pi-incarnate run test:companion",
+    "test:package": "node scripts/package-smoke.mjs",
+    "verify": "npm run check && npm test",
+    "release:check": "npm run verify && npm run test:package && npm pack --dry-run --ignore-scripts",
+    "prepublishOnly": "npm run verify"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.0",
+    "@earendil-works/pi-tui": "0.85.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/avatar-viewer.ts

@@ -0,0 +1,127 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, stripTerminalSequences, truncateToWidth, visibleWidth, type Focusable, type TUI } from "@earendil-works/pi-tui";
+
+import type { IncarnateUiStateV1 } from "./protocol.ts";
+
+export interface AvatarViewerStyles {
+  border(text: string): string;
+  title(text: string): string;
+  dim(text: string): string;
+}
+
+export const plainAvatarViewerStyles: AvatarViewerStyles = {
+  border: (text) => text,
+  title: (text) => text,
+  dim: (text) => text,
+};
+
+function sanitizeInline(value: string): string {
+  return stripTerminalSequences(value)
+    .replace(/[\r\n\t\u0000-\u001f\u007f-\u009f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function pad(value: string, width: number): string {
+  const clipped = truncateToWidth(value, Math.max(0, width), "…");
+  return `${clipped}${" ".repeat(Math.max(0, width - visibleWidth(clipped)))}`;
+}
+
+function center(value: string, width: number): string {
+  const clipped = truncateToWidth(value, Math.max(0, width), "");
+  const available = Math.max(0, width - visibleWidth(clipped));
+  const left = Math.floor(available / 2);
+  return `${" ".repeat(left)}${clipped}${" ".repeat(available - left)}`;
+}
+
+export function renderAvatarViewer(
+  width: number,
+  state: IncarnateUiStateV1,
+  styles: AvatarViewerStyles = plainAvatarViewerStyles,
+  offset = 0,
+  maxAvatarRows = Number.POSITIVE_INFINITY,
+): string[] {
+  const safeWidth = Math.max(1, width);
+  if (safeWidth < 4) return [truncateToWidth("avatar", safeWidth, "")];
+  const innerWidth = safeWidth - 2;
+  if (!state.active || !state.character || !state.avatar?.lines.length) {
+    return [
+      styles.border(`╭${"─".repeat(innerWidth)}╮`),
+      `${styles.border("│")}${pad(styles.dim(" No active avatar"), innerWidth)}${styles.border("│")}`,
+      styles.border(`╰${"─".repeat(innerWidth)}╯`),
+    ];
+  }
+
+  const name = sanitizeInline(state.character.name) || "unknown";
+  const id = sanitizeInline(state.character.id) || "unknown";
+  const title = truncateToWidth(` ${name} / ${id} · full avatar `, innerWidth, "");
+  const top = `${styles.border("╭")}${styles.title(title)}${styles.border("─".repeat(Math.max(0, innerWidth - visibleWidth(title))))}${styles.border("╮")}`;
+  const start = Math.max(0, Math.min(Math.floor(offset), Math.max(0, state.avatar.lines.length - 1)));
+  const visibleLines = state.avatar.lines.slice(start, start + Math.max(1, Math.floor(maxAvatarRows)));
+  const avatarRows = visibleLines.map(
+    (line) => `${styles.border("│")}${center(line, innerWidth)}${styles.border("│")}`,
+  );
+  const range = visibleLines.length < state.avatar.lines.length
+    ? ` ${start + 1}-${start + visibleLines.length}/${state.avatar.lines.length} · ↑/↓ ·`
+    : "";
+  const help = `${styles.border("│")}${pad(styles.dim(`${range} Enter / Esc / q · close`), innerWidth)}${styles.border("│")}`;
+  const bottom = styles.border(`╰${"─".repeat(innerWidth)}╯`);
+  return [top, ...avatarRows, help, bottom];
+}
+
+function viewerStyles(theme: Theme): AvatarViewerStyles {
+  return {
+    border: (text) => theme.fg("border", text),
+    title: (text) => theme.fg("accent", text),
+    dim: (text) => theme.fg("dim", text),
+  };
+}
+
+export class AvatarViewerComponent implements Focusable {
+  focused = false;
+  private readonly state: IncarnateUiStateV1;
+  private readonly theme: Theme;
+  private readonly done: () => void;
+  private readonly tui: TUI | undefined;
+  private offset = 0;
+
+  constructor(state: IncarnateUiStateV1, theme: Theme, done: () => void, tui?: TUI) {
+    this.state = state;
+    this.theme = theme;
+    this.done = done;
+    this.tui = tui;
+  }
+
+  handleInput(data: string): void {
+    const avatarRows = this.state.avatar?.lines.length ?? 0;
+    const viewportRows = this.viewportRows();
+    if (matchesKey(data, "up")) {
+      this.offset = Math.max(0, this.offset - 1);
+      this.tui?.requestRender();
+      return;
+    }
+    if (matchesKey(data, "down")) {
+      this.offset = Math.min(Math.max(0, avatarRows - viewportRows), this.offset + 1);
+      this.tui?.requestRender();
+      return;
+    }
+    if (
+      matchesKey(data, "escape") ||
+      matchesKey(data, "return") ||
+      matchesKey(data, "ctrl+c") ||
+      matchesKey(data, "q")
+    ) {
+      this.done();
+    }
+  }
+
+  private viewportRows(): number {
+    return Math.max(1, (this.tui?.terminal.rows ?? 24) - 5);
+  }
+
+  render(width: number): string[] {
+    return renderAvatarViewer(width, this.state, viewerStyles(this.theme), this.offset, this.viewportRows());
+  }
+
+  invalidate(): void {}
+}

package/src/layout.ts

@@ -0,0 +1,192 @@
+import { basename } from "node:path";
+import { stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import type { IncarnateUiStateV1 } from "./protocol.ts";
+
+export const MAX_FOOTER_ROWS = 6;
+export const PORTRAIT_ROWS = 4;
+const MIN_PORTRAIT_INFO_COLUMNS = 26;
+const AUTO_PORTRAIT_MIN_COLUMNS = 72;
+const AUTO_PORTRAIT_MIN_TERMINAL_ROWS = 20;
+
+export interface FooterSessionInfo {
+  model?: string;
+  provider?: string;
+  availableProviderCount?: number;
+  supportsReasoning?: boolean;
+  thinking?: string;
+  cwd?: string;
+  branch?: string | null;
+  sessionName?: string;
+  contextPercent?: number | null;
+  contextWindow?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  cacheHitPercent?: number;
+  cost?: number;
+  usingSubscription?: boolean;
+  statuses?: string[];
+  terminalRows?: number;
+}
+
+export interface FooterStyles {
+  accent(text: string): string;
+  muted(text: string): string;
+  dim(text: string): string;
+  text(text: string): string;
+  success(text: string): string;
+  warning(text: string): string;
+  error(text: string): string;
+}
+
+export const plainFooterStyles: FooterStyles = {
+  accent: (text) => text,
+  muted: (text) => text,
+  dim: (text) => text,
+  text: (text) => text,
+  success: (text) => text,
+  warning: (text) => text,
+  error: (text) => text,
+};
+
+function sanitizeInline(value: string): string {
+  return stripTerminalSequences(value)
+    .replace(/[\r\n\t\u0000-\u001f\u007f-\u009f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function padToWidth(value: string, width: number): string {
+  const clipped = truncateToWidth(value, Math.max(0, width), "…");
+  return `${clipped}${" ".repeat(Math.max(0, width - visibleWidth(clipped)))}`;
+}
+
+function joinSides(left: string, right: string, width: number): string {
+  if (width <= 0) return "";
+  const safeLeft = truncateToWidth(left, width, "…");
+  const availableRight = width - visibleWidth(safeLeft) - 2;
+  if (availableRight <= 0) return padToWidth(safeLeft, width);
+  const safeRight = truncateToWidth(right, availableRight, "");
+  const gap = Math.max(2, width - visibleWidth(safeLeft) - visibleWidth(safeRight));
+  return padToWidth(`${safeLeft}${" ".repeat(gap)}${safeRight}`, width);
+}
+
+function formatTokens(value: number | undefined): string {
+  const count = Math.max(0, value ?? 0);
+  if (count < 1_000) return String(Math.round(count));
+  if (count < 10_000) return `${(count / 1_000).toFixed(1)}k`;
+  if (count < 1_000_000) return `${Math.round(count / 1_000)}k`;
+  return `${(count / 1_000_000).toFixed(count < 10_000_000 ? 1 : 0)}M`;
+}
+
+function systemRows(width: number, session: FooterSessionInfo, styles: FooterStyles): string[] {
+  const cwd = sanitizeInline(session.cwd ? basename(session.cwd) || session.cwd : "") || "unknown";
+  const safeBranch = sanitizeInline(session.branch ?? "");
+  const branch = safeBranch ? ` (${safeBranch})` : "";
+  const safeSessionName = sanitizeInline(session.sessionName ?? "");
+  const sessionName = safeSessionName ? ` · ${safeSessionName}` : "";
+  const status = (session.statuses ?? []).map(sanitizeInline).filter(Boolean).join(" · ");
+  const location = `${cwd}${branch}${sessionName}${status ? ` · ${status}` : ""}`;
+
+  const usage: string[] = [];
+  if (session.inputTokens) usage.push(`↑${formatTokens(session.inputTokens)}`);
+  if (session.outputTokens) usage.push(`↓${formatTokens(session.outputTokens)}`);
+  if (session.cacheReadTokens) usage.push(`R${formatTokens(session.cacheReadTokens)}`);
+  if (session.cacheWriteTokens) usage.push(`W${formatTokens(session.cacheWriteTokens)}`);
+  if (session.cacheHitPercent !== undefined) usage.push(`CH${session.cacheHitPercent.toFixed(1)}%`);
+  if (session.cost || session.usingSubscription) {
+    usage.push(`$${(session.cost ?? 0).toFixed(3)}${session.usingSubscription ? " (sub)" : ""}`);
+  }
+  const contextText = session.contextPercent === null || session.contextPercent === undefined
+    ? `ctx ?/${formatTokens(session.contextWindow)}`
+    : `ctx ${session.contextPercent.toFixed(1)}%/${formatTokens(session.contextWindow)}`;
+  const context = session.contextPercent !== null && session.contextPercent !== undefined && session.contextPercent > 90
+    ? styles.error(contextText)
+    : session.contextPercent !== null && session.contextPercent !== undefined && session.contextPercent > 70
+      ? styles.warning(contextText)
+      : styles.dim(contextText);
+  const usageText = `${usage.length > 0 ? `${styles.dim(usage.join(" "))} ` : ""}${context}`;
+  const model = sanitizeInline(session.model ?? "") || "no-model";
+  const thinking = sanitizeInline(session.thinking ?? "");
+  const provider = sanitizeInline(session.provider ?? "");
+  const providerPrefix = provider && (session.availableProviderCount ?? 0) > 1 ? `(${provider}) ` : "";
+  const runtime = `${providerPrefix}${model}${session.supportsReasoning && thinking ? ` · think:${thinking}` : ""}`;
+
+  return [
+    padToWidth(styles.dim(location), width),
+    joinSides(usageText, styles.dim(runtime), width),
+  ];
+}
+
+export function sampleAvatarLines(lines: string[], rows = PORTRAIT_ROWS): string[] {
+  if (rows <= 0 || lines.length === 0) return [];
+  if (lines.length <= rows) return [...lines, ...Array.from({ length: rows - lines.length }, () => "")];
+  if (rows === 1) return [lines[Math.floor((lines.length - 1) / 2)] ?? ""];
+  return Array.from({ length: rows }, (_, index) => {
+    const sourceIndex = Math.round((index * (lines.length - 1)) / (rows - 1));
+    return lines[sourceIndex] ?? "";
+  });
+}
+
+function portraitRows(
+  width: number,
+  state: IncarnateUiStateV1,
+  session: FooterSessionInfo,
+  styles: FooterStyles,
+): string[] | undefined {
+  if (!state.active || !state.character || !state.avatar?.lines.length) return undefined;
+  if (state.avatarMode === "off" || state.avatarMode === "compact") return undefined;
+  if (
+    state.avatarMode === "auto" &&
+    (width < AUTO_PORTRAIT_MIN_COLUMNS || (session.terminalRows ?? 24) < AUTO_PORTRAIT_MIN_TERMINAL_ROWS)
+  ) {
+    return undefined;
+  }
+
+  const avatarWidth = Math.min(state.avatar.width, width);
+  const infoWidth = width - avatarWidth - 3;
+  if (avatarWidth <= 0 || infoWidth < MIN_PORTRAIT_INFO_COLUMNS) return undefined;
+
+  const character = state.character;
+  const name = sanitizeInline(character.name) || "unknown";
+  const id = sanitizeInline(character.id) || "unknown";
+  const mood = sanitizeInline(character.mood ?? "") || "none";
+  const info = [
+    `${styles.success("●")} ${styles.accent(name)} ${styles.dim(`/ ${id}`)}`,
+    `${styles.muted("mood")} ${styles.text(mood)}`,
+    `${styles.muted("forms")} ${styles.text(`${character.forms.available}/${character.forms.total}`)} ${styles.dim(`· ${character.source}`)}`,
+    styles.dim("/incarnate · configure"),
+  ];
+  return sampleAvatarLines(state.avatar.lines).map((line, index) => {
+    const avatar = padToWidth(line, avatarWidth);
+    const details = padToWidth(info[index] ?? "", infoWidth);
+    return `${avatar} ${styles.accent("│")} ${details}`;
+  });
+}
+
+function compactCharacterRow(width: number, state: IncarnateUiStateV1, styles: FooterStyles): string[] {
+  if (!state.active || !state.character || state.avatarMode === "off") return [];
+  const name = sanitizeInline(state.character.name) || "unknown";
+  const id = sanitizeInline(state.character.id) || "unknown";
+  const safeMood = sanitizeInline(state.character.mood ?? "");
+  const mood = safeMood ? ` · mood:${safeMood}` : "";
+  return [
+    padToWidth(
+      `${styles.success("●")} ${styles.accent(name)} ${styles.dim(`/ ${id}${mood}`)}`,
+      width,
+    ),
+  ];
+}
+
+export function renderFooter(
+  width: number,
+  state: IncarnateUiStateV1,
+  session: FooterSessionInfo = {},
+  styles: FooterStyles = plainFooterStyles,
+): string[] {
+  const safeWidth = Math.max(1, width);
+  const character = portraitRows(safeWidth, state, session, styles) ?? compactCharacterRow(safeWidth, state, styles);
+  return [...character, ...systemRows(safeWidth, session, styles)].slice(0, MAX_FOOTER_ROWS);
+}

package/src/protocol.ts

@@ -0,0 +1,85 @@
+export const UI_REQUEST_STATE_EVENT = "pi-incarnate:ui:request-state-v1";
+export const UI_STATE_EVENT = "pi-incarnate:ui:state-v1";
+
+export type CharacterSource = "built-in" | "personal";
+export type AvatarMode = "auto" | "full" | "compact" | "off";
+
+export interface IncarnateUiStateV1 {
+  version: 1;
+  active: boolean;
+  avatarMode: AvatarMode;
+  character?: {
+    id: string;
+    name: string;
+    mood?: string;
+    source: CharacterSource;
+    forms: {
+      available: number;
+      total: number;
+    };
+  };
+  avatar?: {
+    lines: string[];
+    width: number;
+    height: number;
+    truncated: boolean;
+  };
+}
+
+export function isIncarnateUiStateV1(value: unknown): value is IncarnateUiStateV1 {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Record<string, unknown>;
+  if (
+    candidate.version !== 1 ||
+    typeof candidate.active !== "boolean" ||
+    typeof candidate.avatarMode !== "string" ||
+    !["auto", "full", "compact", "off"].includes(candidate.avatarMode)
+  ) {
+    return false;
+  }
+
+  if (candidate.active) {
+    if (!candidate.character || typeof candidate.character !== "object") return false;
+    const character = candidate.character as Record<string, unknown>;
+    if (
+      typeof character.id !== "string" ||
+      typeof character.name !== "string" ||
+      (character.mood !== undefined && typeof character.mood !== "string") ||
+      (character.source !== "built-in" && character.source !== "personal") ||
+      !character.forms ||
+      typeof character.forms !== "object"
+    ) {
+      return false;
+    }
+    const forms = character.forms as Record<string, unknown>;
+    if (
+      typeof forms.available !== "number" ||
+      !Number.isInteger(forms.available) ||
+      forms.available < 0 ||
+      typeof forms.total !== "number" ||
+      !Number.isInteger(forms.total) ||
+      forms.total < forms.available
+    ) {
+      return false;
+    }
+  }
+
+  if (candidate.avatar !== undefined) {
+    if (!candidate.avatar || typeof candidate.avatar !== "object") return false;
+    const avatar = candidate.avatar as Record<string, unknown>;
+    if (
+      !Array.isArray(avatar.lines) ||
+      avatar.lines.length > 16 ||
+      !avatar.lines.every((line) => typeof line === "string") ||
+      typeof avatar.width !== "number" ||
+      !Number.isInteger(avatar.width) ||
+      avatar.width < 0 ||
+      avatar.width > 48 ||
+      avatar.height !== avatar.lines.length ||
+      typeof avatar.truncated !== "boolean"
+    ) {
+      return false;
+    }
+  }
+  return true;
+}