pi-incarnate-ui 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog
 
-## 0.1.0 - Unreleased
+## Unreleased
+
+## 0.2.0 - 2026-09-11
+
+- Render validated PNG avatars through Pi's inline-image component with aspect-ratio-preserving Footer and overlay bounds.
+- Fall back automatically to ANSI/TXT or compact character status when image protocols are unavailable, disabled, or fail to render.
+- Reuse image IDs across redraws and cover Kitty, iTerm2, resize, overlay, and no-image capability branches.
+- Keep primary character values readable when Pi's configured theme does not match the terminal background by using the terminal foreground with bold emphasis.
+
+## 0.1.0 - 2026-09-09
 
 - 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.

package/README.md

@@ -5,14 +5,14 @@
 它使用 Pi 的公开 `setFooter()` API，把角色呈现和必要的 Pi 运行信息组合成固定底部区域：
 
 - 固定区域严格不超过 6 行，避免压缩对话和输入框。
-- 宽终端使用同一份头像自动生成 4 行纵向采样预览，旁边显示角色、mood、来源和表单状态；不要求额外维护缩略图。
+- 宽终端优先在 4 行预算内等比显示 `avatar.png`，旁边显示角色、mood、来源和表单状态；没有 PNG 或图片协议不可用时使用 ANSI/TXT 四行采样回退。
 - 终端窄于 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 扩展的共存。
+当前版本为 `0.2.0`，新增 PNG 等比头像、兼容回退和主题错配时的主信息对比度保护。可使用 `pi install npm:pi-incarnate-ui` 安装；当前仍不处理与其他自定义 Footer 扩展的共存。
 
 ## Development
 
@@ -27,7 +27,7 @@ pi --no-extensions \
 
 `test:companion` 要求核心仓库位于同级目录 `/path/to/pi-incarnate`。它加载两个真实扩展入口，验证两种加载顺序、状态生命周期、未知协议版本和缺失另一端的降级。
 
-启动后通过 `/incarnate` 选择角色。核心扩展只管理人格、角色资源和安全清理；所有终端绘制均由本 UI 扩展负责。未加载 UI 时人格仍然生效，但不显示角色图。
+启动后通过 `/incarnate` 选择角色。核心扩展只管理人格、角色资源和安全清理；所有终端绘制均由本 UI 扩展负责。未加载 UI 时人格仍然生效，但不显示角色图。PNG 通过 Pi 的 `Image` 组件使用 Kitty 或 iTerm2 协议渲染，按原始像素尺寸与终端 cell 尺寸等比缩放；Pi 禁用图片或终端不支持时不会输出占位图。
 
 需要查看未经四行采样的完整头像时运行：
 
@@ -35,14 +35,15 @@ pi --no-extensions \
 /incarnate-ui
 ```
 
-查看器只在 TUI 中打开临时居中浮层，使用核心已经清理并限制为最多 48×16 的头像数据，不读取角色目录，也不改变 Footer 模式。终端高度不足时可用 `↑` / `↓` 滚动查看全部头像行。
+查看器只在 TUI 中打开临时居中浮层，使用核心已经验证的 PNG 或清理并限制为最多 48×16 的文本头像数据，不读取角色目录，也不改变 Footer 模式。PNG 在浮层可用空间内等比缩放；文本头像在终端高度不足时可用 `↑` / `↓` 滚动查看全部行。
 
 ## 当前边界
 
 - 只在 TUI 模式设置 Footer；RPC、JSON 和 print 模式不接管表现层。
 - 角色状态由版本化的 `pi.events` 协议传递，UI 不直接读取角色目录。
 - `compact` 使用 3 行布局；`auto` 和 `full` 在宽度足够时使用最多 6 行布局；`off` 或未激活状态不接管 Footer。
-- 四行头像是从完整资源自动采样的常驻预览，不等同于完整原图；完整内容由按需查看器提供。
+- PNG 常驻预览保持宽高比并限制为四行；ANSI/TXT 回退仍从完整文本资源抽样，因此不等同于完整原图。完整内容由按需查看器提供。
+- PNG-only 角色在图片协议不可用时降级为紧凑角色状态；建议同时提供 `avatar.ansi` 或 `avatar.txt`。
 - 完整头像查看器是临时 overlay，不占用常驻布局；无活动头像或非 TUI 模式时只给出提示。
 - 当前角色状态仍由 pi-incarnate 按 session 管理；新会话默认关闭，需要重新选择角色，此时显示 Pi 自身的默认 Footer。
 - Pi 0.85.0 的公开扩展上下文不暴露通用订阅检测和 auto-compaction 开关；UI 只保留默认 Footer 可公开重建的信息，并沿用 Pi 对 `kimi-coding` 的已知订阅标记。其他 provider 的内部订阅状态与 auto-compaction 标记不显示。

package/SECURITY.md

@@ -2,10 +2,12 @@
 
 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.
+`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 and PNG structure, 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 Footer renderer bounds every output line to the available terminal width and emits at most six rows. Protocol validation accepts at most 16 text-avatar lines and 48 visible columns, or a PNG up to 512 KiB, 2048 px per dimension, and 4,194,304 pixels. It verifies canonical base64, the PNG signature, IHDR dimensions, and metadata consistency before passing image data to Pi's `Image` component. 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.
+The optional full-avatar overlay renders only the same bounded in-memory snapshot; it does not read files. PNG rendering preserves aspect ratio within the assigned overlay bounds; text rows are clipped to the assigned width. Its title metadata is sanitized, and it closes without changing character state.
+
+Inline PNG output is emitted only when Pi reports Kitty or iTerm2 image support. Unsupported, disabled, or failed image rendering falls back to the supplied ANSI/TXT avatar; PNG-only characters fall back to the compact status row. Image IDs are reused across redraws and size changes so Pi can replace placements without accumulating stale image data.
 
 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

@@ -4,10 +4,11 @@ import type {
   ReadonlyFooterDataProvider,
   Theme,
 } from "@earendil-works/pi-coding-agent";
-import type { TUI } from "@earendil-works/pi-tui";
+import { getCapabilities, 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 { IncarnateFooterComponent } from "../src/footer-component.ts";
+import { type FooterSessionInfo, type FooterStyles } from "../src/layout.ts";
 import {
   isIncarnateUiStateV1,
   UI_REQUEST_STATE_EVENT,
@@ -22,7 +23,9 @@ function themeStyles(theme: Theme): FooterStyles {
     accent: (text) => theme.fg("accent", text),
     muted: (text) => theme.fg("muted", text),
     dim: (text) => theme.fg("dim", text),
-    text: (text) => theme.fg("text", text),
+    // Use the terminal foreground for primary values. This stays readable when
+    // Pi's configured light/dark theme does not match the terminal background.
+    text: (text) => theme.bold(text),
     success: (text) => theme.fg("success", text),
     warning: (text) => theme.fg("warning", text),
     error: (text) => theme.fg("error", text),
@@ -120,11 +123,18 @@ export default function incarnateUiExtension(pi: ExtensionAPI): void {
     context.ui.setFooter((footerTui, theme, footerData) => {
       tui = footerTui;
       const unsubscribe = footerData.onBranchChange(requestRender);
+      const footer = new IncarnateFooterComponent(
+        () => state,
+        () => sessionInfo(context, footerData, footerTui),
+        themeStyles(theme),
+      );
       return {
         render(width: number): string[] {
-          return renderFooter(width, state, sessionInfo(context, footerData, footerTui), themeStyles(theme));
+          return footer.render(width);
+        },
+        invalidate() {
+          footer.invalidate();
         },
-        invalidate() {},
         dispose() {
           unsubscribe();
           if (tui === footerTui) tui = undefined;
@@ -165,17 +175,21 @@ export default function incarnateUiExtension(pi: ExtensionAPI): void {
         ctx.ui.notify("The full avatar viewer is available only in TUI mode", "warning");
         return;
       }
-      if (!state.active || !state.avatar?.lines.length) {
+      if (!state.active || !state.avatar || (!state.avatar.lines.length && !state.avatar.image)) {
         ctx.ui.notify("No active avatar. Enable a character and its avatar first.", "warning");
         return;
       }
+      if (!state.avatar.lines.length && state.avatar.image && !getCapabilities().images) {
+        ctx.ui.notify("This terminal cannot render PNG avatars. Add avatar.ansi or avatar.txt as a fallback.", "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)),
+            width: state.avatar.image ? 54 : Math.max(24, Math.min(54, state.avatar.width + 4)),
             maxHeight: 20,
             margin: 1,
           },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-incarnate-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A compact character-aware footer for pi-incarnate",
   "author": "NandySun",
   "type": "module",

package/src/avatar-viewer.ts

@@ -1,7 +1,18 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { matchesKey, stripTerminalSequences, truncateToWidth, visibleWidth, type Focusable, type TUI } from "@earendil-works/pi-tui";
+import {
+  Image,
+  compositeTuiLine,
+  getCapabilities,
+  matchesKey,
+  stripTerminalSequences,
+  truncateToWidth,
+  visibleWidth,
+  type Focusable,
+  type TUI,
+} from "@earendil-works/pi-tui";
 
 import type { IncarnateUiStateV1 } from "./protocol.ts";
+import { calculateBoundedImageSize, containsInlineImage } from "./inline-image.ts";
 
 export interface AvatarViewerStyles {
   border(text: string): string;
@@ -15,6 +26,11 @@ export const plainAvatarViewerStyles: AvatarViewerStyles = {
   dim: (text) => text,
 };
 
+export interface RenderedViewerImage {
+  lines: string[];
+  width: number;
+}
+
 function sanitizeInline(value: string): string {
   return stripTerminalSequences(value)
     .replace(/[\r\n\t\u0000-\u001f\u007f-\u009f]+/g, " ")
@@ -40,11 +56,12 @@ export function renderAvatarViewer(
   styles: AvatarViewerStyles = plainAvatarViewerStyles,
   offset = 0,
   maxAvatarRows = Number.POSITIVE_INFINITY,
+  renderedImage?: RenderedViewerImage,
 ): 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) {
+  if (!state.active || !state.character || (!state.avatar?.lines.length && !renderedImage)) {
     return [
       styles.border(`╭${"─".repeat(innerWidth)}╮`),
       `${styles.border("│")}${pad(styles.dim(" No active avatar"), innerWidth)}${styles.border("│")}`,
@@ -56,13 +73,18 @@ export function renderAvatarViewer(
   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 start = Math.max(0, Math.min(Math.floor(offset), Math.max(0, (state.avatar?.lines.length ?? 0) - 1)));
+  const visibleLines = renderedImage
+    ? renderedImage.lines
+    : state.avatar!.lines.slice(start, start + Math.max(1, Math.floor(maxAvatarRows)));
+  const avatarRows = visibleLines.map((line) => {
+    if (!renderedImage) return `${styles.border("│")}${center(line, innerWidth)}${styles.border("│")}`;
+    const left = 1 + Math.floor(Math.max(0, innerWidth - renderedImage.width) / 2);
+    const base = `${styles.border("│")}${" ".repeat(innerWidth)}${styles.border("│")}`;
+    return compositeTuiLine(base, line, left, renderedImage.width, safeWidth);
+  });
+  const range = !renderedImage && 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)}╯`);
@@ -84,6 +106,11 @@ export class AvatarViewerComponent implements Focusable {
   private readonly done: () => void;
   private readonly tui: TUI | undefined;
   private offset = 0;
+  private image?: Image;
+  private imageData?: string;
+  private imageProtocol?: string;
+  private imageColumns?: number;
+  private imageRows?: number;
 
   constructor(state: IncarnateUiStateV1, theme: Theme, done: () => void, tui?: TUI) {
     this.state = state;
@@ -119,9 +146,51 @@ export class AvatarViewerComponent implements Focusable {
     return Math.max(1, (this.tui?.terminal.rows ?? 24) - 5);
   }
 
+  private renderImage(width: number): RenderedViewerImage | undefined {
+    const source = this.state.avatar?.image;
+    const protocol = getCapabilities().images;
+    if (!source || !protocol || width < 4) return undefined;
+    const size = calculateBoundedImageSize(
+      { widthPx: source.widthPx, heightPx: source.heightPx },
+      Math.max(1, width - 2),
+      this.viewportRows(),
+    );
+    if (
+      !this.image ||
+      this.imageData !== source.data ||
+      this.imageProtocol !== protocol ||
+      this.imageColumns !== size.columns ||
+      this.imageRows !== size.rows
+    ) {
+      const imageId = this.image?.getImageId();
+      this.image = new Image(
+        source.data,
+        source.mimeType,
+        { fallbackColor: (text) => this.theme.fg("dim", text) },
+        { maxWidthCells: size.columns, maxHeightCells: size.rows, filename: "avatar.png", imageId },
+        { widthPx: source.widthPx, heightPx: source.heightPx },
+      );
+      this.imageData = source.data;
+      this.imageProtocol = protocol;
+      this.imageColumns = size.columns;
+      this.imageRows = size.rows;
+    }
+    const lines = this.image.render(size.columns + 2);
+    return containsInlineImage(lines) ? { lines, width: size.columns } : undefined;
+  }
+
   render(width: number): string[] {
-    return renderAvatarViewer(width, this.state, viewerStyles(this.theme), this.offset, this.viewportRows());
+    return renderAvatarViewer(
+      width,
+      this.state,
+      viewerStyles(this.theme),
+      this.offset,
+      this.viewportRows(),
+      this.renderImage(width),
+    );
   }
 
-  invalidate(): void {}
+  invalidate(): void {
+    this.image?.invalidate();
+  }
 }

package/src/footer-component.ts

@@ -0,0 +1,81 @@
+import {
+  Image,
+  getCapabilities,
+  type Component,
+} from "@earendil-works/pi-tui";
+
+import {
+  footerImageBounds,
+  renderFooter,
+  type FooterSessionInfo,
+  type FooterStyles,
+  type RenderedAvatarImage,
+} from "./layout.ts";
+import type { IncarnateUiStateV1 } from "./protocol.ts";
+import { calculateBoundedImageSize, containsInlineImage } from "./inline-image.ts";
+
+export class IncarnateFooterComponent implements Component {
+  private readonly getState: () => IncarnateUiStateV1;
+  private readonly getSession: () => FooterSessionInfo;
+  private readonly styles: FooterStyles;
+  private image?: Image;
+  private imageData?: string;
+  private imageProtocol?: string;
+  private imageColumns?: number;
+  private imageRows?: number;
+
+  constructor(
+    getState: () => IncarnateUiStateV1,
+    getSession: () => FooterSessionInfo,
+    styles: FooterStyles,
+  ) {
+    this.getState = getState;
+    this.getSession = getSession;
+    this.styles = styles;
+  }
+
+  private renderImage(width: number, state: IncarnateUiStateV1, session: FooterSessionInfo): RenderedAvatarImage | undefined {
+    const source = state.avatar?.image;
+    const bounds = footerImageBounds(width, state, session);
+    const protocol = getCapabilities().images;
+    if (!source || !bounds || !protocol) return undefined;
+
+    const size = calculateBoundedImageSize(
+      { widthPx: source.widthPx, heightPx: source.heightPx },
+      bounds.maxWidth,
+      bounds.maxHeight,
+    );
+    if (
+      !this.image ||
+      this.imageData !== source.data ||
+      this.imageProtocol !== protocol ||
+      this.imageColumns !== size.columns ||
+      this.imageRows !== size.rows
+    ) {
+      const imageId = this.image?.getImageId();
+      this.image = new Image(
+        source.data,
+        source.mimeType,
+        { fallbackColor: this.styles.dim },
+        { maxWidthCells: size.columns, maxHeightCells: size.rows, filename: "avatar.png", imageId },
+        { widthPx: source.widthPx, heightPx: source.heightPx },
+      );
+      this.imageData = source.data;
+      this.imageProtocol = protocol;
+      this.imageColumns = size.columns;
+      this.imageRows = size.rows;
+    }
+    const lines = this.image.render(size.columns + 2);
+    return containsInlineImage(lines) ? { lines, width: size.columns } : undefined;
+  }
+
+  render(width: number): string[] {
+    const state = this.getState();
+    const session = this.getSession();
+    return renderFooter(width, state, session, this.styles, this.renderImage(width, state, session));
+  }
+
+  invalidate(): void {
+    this.image?.invalidate();
+  }
+}

package/src/inline-image.ts

@@ -0,0 +1,22 @@
+import { getCellDimensions } from "@earendil-works/pi-tui";
+
+export function calculateBoundedImageSize(
+  dimensions: { widthPx: number; heightPx: number },
+  maxWidthCells: number,
+  maxHeightCells: number,
+): { columns: number; rows: number } {
+  const maximumWidth = Math.max(1, Math.floor(maxWidthCells));
+  const maximumHeight = Math.max(1, Math.floor(maxHeightCells));
+  const cells = getCellDimensions();
+  const widthScale = (maximumWidth * cells.widthPx) / Math.max(1, dimensions.widthPx);
+  const heightScale = (maximumHeight * cells.heightPx) / Math.max(1, dimensions.heightPx);
+  const scale = Math.min(widthScale, heightScale);
+  return {
+    columns: Math.max(1, Math.min(maximumWidth, Math.ceil((dimensions.widthPx * scale) / cells.widthPx))),
+    rows: Math.max(1, Math.min(maximumHeight, Math.ceil((dimensions.heightPx * scale) / cells.heightPx))),
+  };
+}
+
+export function containsInlineImage(lines: string[]): boolean {
+  return lines.some((line) => line.includes("\u001b_G") || line.includes("\u001b]1337;File="));
+}

package/src/layout.ts

@@ -1,5 +1,5 @@
 import { basename } from "node:path";
-import { stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { compositeTuiLine, stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 import type { IncarnateUiStateV1 } from "./protocol.ts";
 
@@ -9,6 +9,11 @@ const MIN_PORTRAIT_INFO_COLUMNS = 26;
 const AUTO_PORTRAIT_MIN_COLUMNS = 72;
 const AUTO_PORTRAIT_MIN_TERMINAL_ROWS = 20;
 
+export interface RenderedAvatarImage {
+  lines: string[];
+  width: number;
+}
+
 export interface FooterSessionInfo {
   model?: string;
   provider?: string;
@@ -130,22 +135,36 @@ export function sampleAvatarLines(lines: string[], rows = PORTRAIT_ROWS): string
   });
 }
 
+function portraitModeEnabled(width: number, state: IncarnateUiStateV1, session: FooterSessionInfo): boolean {
+  if (!state.active || !state.character || state.avatarMode === "off" || state.avatarMode === "compact") return false;
+  return !(
+    state.avatarMode === "auto" &&
+    (width < AUTO_PORTRAIT_MIN_COLUMNS || (session.terminalRows ?? 24) < AUTO_PORTRAIT_MIN_TERMINAL_ROWS)
+  );
+}
+
+export function footerImageBounds(
+  width: number,
+  state: IncarnateUiStateV1,
+  session: FooterSessionInfo,
+): { maxWidth: number; maxHeight: number } | undefined {
+  if (!state.avatar?.image || !portraitModeEnabled(width, state, session)) return undefined;
+  const maxWidth = Math.min(48, width - MIN_PORTRAIT_INFO_COLUMNS - 3);
+  return maxWidth >= 4 ? { maxWidth, maxHeight: PORTRAIT_ROWS } : undefined;
+}
+
 function portraitRows(
   width: number,
   state: IncarnateUiStateV1,
   session: FooterSessionInfo,
   styles: FooterStyles,
+  renderedImage?: RenderedAvatarImage,
 ): 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;
-  }
+  if (!state.active || !state.character || !state.avatar || !portraitModeEnabled(width, state, session)) return undefined;
+  const useImage = Boolean(renderedImage?.lines.length && state.avatar.image);
+  if (!useImage && state.avatar.lines.length === 0) return undefined;
 
-  const avatarWidth = Math.min(state.avatar.width, width);
+  const avatarWidth = Math.min(useImage ? renderedImage!.width : state.avatar.width, width);
   const infoWidth = width - avatarWidth - 3;
   if (avatarWidth <= 0 || infoWidth < MIN_PORTRAIT_INFO_COLUMNS) return undefined;
 
@@ -159,10 +178,15 @@ function portraitRows(
     `${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 sourceLines = useImage
+    ? [...renderedImage!.lines, ...Array.from({ length: Math.max(0, PORTRAIT_ROWS - renderedImage!.lines.length) }, () => "")]
+        .slice(0, PORTRAIT_ROWS)
+    : sampleAvatarLines(state.avatar.lines);
+  return sourceLines.map((line, index) => {
     const avatar = padToWidth(line, avatarWidth);
     const details = padToWidth(info[index] ?? "", infoWidth);
-    return `${avatar} ${styles.accent("│")} ${details}`;
+    const base = `${" ".repeat(avatarWidth)} ${styles.accent("│")} ${details}`;
+    return useImage ? compositeTuiLine(base, line, 0, avatarWidth, width) : `${avatar} ${styles.accent("│")} ${details}`;
   });
 }
 
@@ -185,8 +209,9 @@ export function renderFooter(
   state: IncarnateUiStateV1,
   session: FooterSessionInfo = {},
   styles: FooterStyles = plainFooterStyles,
+  renderedImage?: RenderedAvatarImage,
 ): string[] {
   const safeWidth = Math.max(1, width);
-  const character = portraitRows(safeWidth, state, session, styles) ?? compactCharacterRow(safeWidth, state, styles);
+  const character = portraitRows(safeWidth, state, session, styles, renderedImage) ?? compactCharacterRow(safeWidth, state, styles);
   return [...character, ...systemRows(safeWidth, session, styles)].slice(0, MAX_FOOTER_ROWS);
 }

package/src/protocol.ts

@@ -3,6 +3,17 @@ export const UI_STATE_EVENT = "pi-incarnate:ui:state-v1";
 
 export type CharacterSource = "built-in" | "personal";
 export type AvatarMode = "auto" | "full" | "compact" | "off";
+export const AVATAR_PNG_MAX_BYTES = 512 * 1024;
+export const AVATAR_PNG_MAX_DIMENSION = 2048;
+export const AVATAR_PNG_MAX_PIXELS = 2048 * 2048;
+
+export interface IncarnateAvatarImageV1 {
+  mimeType: "image/png";
+  data: string;
+  widthPx: number;
+  heightPx: number;
+  bytes: number;
+}
 
 export interface IncarnateUiStateV1 {
   version: 1;
@@ -23,9 +34,56 @@ export interface IncarnateUiStateV1 {
     width: number;
     height: number;
     truncated: boolean;
+    image?: IncarnateAvatarImageV1;
   };
 }
 
+function decodeCanonicalPng(value: string, expectedBytes: number): Buffer | undefined {
+  if (
+    value.length === 0 ||
+    value.length > Math.ceil(AVATAR_PNG_MAX_BYTES / 3) * 4 ||
+    value.length % 4 !== 0 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)
+  ) {
+    return undefined;
+  }
+  const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+  if ((value.length / 4) * 3 - padding !== expectedBytes) return undefined;
+  const decoded = Buffer.from(value, "base64");
+  return decoded.toString("base64") === value ? decoded : undefined;
+}
+
+function isAvatarImage(value: unknown): value is IncarnateAvatarImageV1 {
+  if (!value || typeof value !== "object") return false;
+  const image = value as Record<string, unknown>;
+  if (!(
+    image.mimeType === "image/png" &&
+    typeof image.data === "string" &&
+    typeof image.widthPx === "number" &&
+    Number.isInteger(image.widthPx) &&
+    image.widthPx > 0 &&
+    image.widthPx <= AVATAR_PNG_MAX_DIMENSION &&
+    typeof image.heightPx === "number" &&
+    Number.isInteger(image.heightPx) &&
+    image.heightPx > 0 &&
+    image.heightPx <= AVATAR_PNG_MAX_DIMENSION &&
+    image.widthPx * image.heightPx <= AVATAR_PNG_MAX_PIXELS &&
+    typeof image.bytes === "number" &&
+    Number.isInteger(image.bytes) &&
+    image.bytes > 0 &&
+    image.bytes <= AVATAR_PNG_MAX_BYTES
+  )) return false;
+  const decoded = decodeCanonicalPng(image.data, image.bytes);
+  return Boolean(
+    decoded &&
+    decoded.byteLength >= 24 &&
+    decoded.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) &&
+    decoded.toString("ascii", 12, 16) === "IHDR" &&
+    decoded.readUInt32BE(16) === image.widthPx &&
+    decoded.readUInt32BE(20) === image.heightPx
+  );
+}
+
 export function isIncarnateUiStateV1(value: unknown): value is IncarnateUiStateV1 {
   if (!value || typeof value !== "object") return false;
   const candidate = value as Record<string, unknown>;
@@ -76,7 +134,8 @@ export function isIncarnateUiStateV1(value: unknown): value is IncarnateUiStateV
       avatar.width < 0 ||
       avatar.width > 48 ||
       avatar.height !== avatar.lines.length ||
-      typeof avatar.truncated !== "boolean"
+      typeof avatar.truncated !== "boolean" ||
+      (avatar.image !== undefined && !isAvatarImage(avatar.image))
     ) {
       return false;
     }