pi-incarnate 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,7 +2,14 @@
 
 All notable changes to this project are documented here.
 
-## 0.2.0 - Unreleased
+## Unreleased
+
+## 0.3.0 - 2026-09-11
+
+- Add validated `avatar.png` primary avatars with bounded dimensions and file size, while retaining one `avatar.ansi` or `avatar.txt` fallback.
+- Carry PNG avatars through personal import/removal, portable v1 character packages, and the backward-compatible v1 companion UI snapshot.
+
+## 0.2.0 - 2026-09-09
 
 - Keep unselected keyboard-menu options readable across light/dark terminal mismatches by using the terminal foreground in bold instead of forcing a theme text color.
 - Add an eight-scenario persona evaluation plan and isolated real-Pi RPC runner with scenario filtering and repeated sampling.

package/README.md

@@ -2,7 +2,7 @@
 
 让角色进入 Pi Agent 的对话现场：通过可编辑角色卡、稳定的人格层和会话内 mood，让非 coding 对话拥有更强的在场感，同时保留 Pi 原有工具、安全边界和任务完成能力。头像与状态显示由可选的 `pi-incarnate-ui` 配套扩展提供。
 
-最新 npm 版本仍为 `0.1.0`；当前工作区是尚未发布的 `0.2.0` 本地候选，包含交互菜单、角色资源管理、联合协议门禁和人格回归工具。项目已在 Pi `0.85.0` 验证，要求 Node.js `>=22.19.0`。当前版本不做世界书、自动长期记忆或隐式角色切换。
+当前版本为 `0.3.0`，新增 PNG 主头像及 ANSI/TXT 兼容回退。项目已在 Pi `0.85.0` 验证，要求 Node.js `>=22.19.0`。当前版本不做世界书、自动长期记忆或隐式角色切换。
 
 ## 安装与启动
 
@@ -49,8 +49,6 @@ pi install /path/to/pi-incarnate
 pi install npm:pi-incarnate
 ```
 
-如果 npm registry 中尚未提供目标版本，请先使用上面的本地路径安装方式。
-
 本地包由 Pi 设置管理；需要移除时运行：
 
 ```bash
@@ -122,8 +120,9 @@ pi remove /path/to/pi-incarnate
 characters/
 └── my-character/
     ├── CHARACTER.md
+    ├── avatar.png          # 可选，支持终端图片协议时作为主头像
     ├── avatar.txt          # 可选，纯文本头像
-    ├── avatar.ansi         # 可选，受限 ANSI 真彩头像；优先于 avatar.txt
+    ├── avatar.ansi         # 可选，受限 ANSI 真彩回退；优先于 avatar.txt
     └── forms/              # 可选
 ```
 
@@ -174,11 +173,13 @@ Default: warm
 
 如果个人角色卡已经损坏，运行 `/incarnate` → `Character library` → `Add or restore character` → `Repair invalid character card`。菜单只列出目录 ID 安全、位于个人角色根目录内，且属于“卡片格式错误”或“缺少卡片”的项目。格式错误的 UTF-8 卡片会在原内容上编辑；缺少卡片时会提供完整模板。无效编码、符号链接和越界目录不会在 TUI 中打开。
 
-头像可以通过 `/incarnate` → `Character library` → `Edit character` → `Manage character avatar` 导入或移除。选择角色后输入 `.ansi` 或 `.txt` 文件路径；支持绝对路径、相对当前工作目录的路径、`~/...`、`file://...`、成对引号和终端拖放常见的转义空格。导入内置角色时会先请求创建个人覆盖副本，包内资源不会被修改。
+头像可以通过 `/incarnate` → `Character library` → `Edit character` → `Manage character avatar` 导入或移除。选择角色后输入 `.png`、`.ansi` 或 `.txt` 文件路径；支持绝对路径、相对当前工作目录的路径、`~/...`、`file://...`、成对引号和终端拖放常见的转义空格。导入内置角色时会先请求创建个人覆盖副本，包内资源不会被修改。
+
+`avatar.png` 是主头像。支持 Kitty 或 iTerm2 图片协议时，`pi-incarnate-ui` 会按 PNG 像素尺寸和终端 cell 尺寸等比缩放；不支持图片、图片被 Pi 禁用或渲染失败时，自动回退到 `avatar.ansi`，其次是 `avatar.txt`。只有 PNG 而无法显示图片时使用紧凑角色状态，不影响人格。PNG 最大 512 KiB，宽高各不超过 2048 px，总像素不超过 4,194,304；导入时检查 PNG 签名、chunk checksum、IHDR、必要数据块和尺寸。
 
-`avatar.txt` 是纯文本格式，会去除 ANSI 和终端控制序列。`avatar.ansi` 用于彩色头像，存在时优先于 `avatar.txt`；它只保留标准色、256 色、24-bit 前景/背景色及 reset，光标移动、清屏、OSC、超链接和其他控制序列一律删除。两种格式都要求 UTF-8，最大 64 KiB、16 行、每行 48 个终端列。ANSI 每行会强制 reset，防止颜色泄漏到 Pi 界面。头像损坏或不可读时只降级为角色状态行，不会关闭已经启用的人格。
+`avatar.txt` 是纯文本格式，会去除 ANSI 和终端控制序列。`avatar.ansi` 用于彩色回退，存在时优先于 `avatar.txt`；它只保留标准色、256 色、24-bit 前景/背景色及 reset，光标移动、清屏、OSC、超链接和其他控制序列一律删除。两种文本格式都要求 UTF-8，最大 64 KiB、16 行、每行 48 个终端列。ANSI 每行会强制 reset，防止颜色泄漏到 Pi 界面。头像损坏或不可读时只降级为角色状态行，不会关闭已经启用的人格。
 
-菜单导入会把清理后的安全版本写入个人角色目录，并拒绝需要裁剪的资源，避免静默损失图像。导入一种格式会移除另一种格式，确保新头像立即生效；写入使用同目录临时文件替换。移除操作需要确认，只删除个人副本中的 `avatar.ansi` 和 `avatar.txt`。
+菜单导入会把验证或清理后的安全版本写入个人角色目录，并拒绝超出边界或需要裁剪的资源。导入 PNG 会保留已有文本回退；导入 ANSI/TXT 会互相替换但保留 PNG 主图。写入使用同目录临时文件替换。移除操作需要确认，并删除个人副本中的 `avatar.png`、`avatar.ansi` 和 `avatar.txt`。
 
 个人角色可以通过 `/incarnate` → `Character library` → `Manage or export character` 重命名或归档；恢复入口位于 `Add or restore character`。重命名只修改安全目录 ID，不改角色卡中的显示名；如果角色正在使用，会同步更新当前会话。归档会在确认后把完整角色目录移到：
 
@@ -196,11 +197,11 @@ Default: warm
 <character-id>.pi-character.json
 ```
 
-导出只收集 `CHARACTER.md`、运行时优先使用的一个头像，以及角色卡中已经声明且当前可用的 Markdown 表单。未知文件、未声明文件、缺失或无效表单和被另一格式遮蔽的头像不会进入角色包。确认界面会显示实际包含的头像和表单数量；偏好表单可能包含私人信息，分享前应直接打开 JSON 检查。
+导出只收集 `CHARACTER.md`、可用的 PNG 主头像、一个运行时优先的 ANSI/TXT 回退，以及角色卡中已经声明且当前可用的 Markdown 表单。PNG 在 JSON 中使用显式 base64 编码；旧的纯文本 v1 角色包仍可导入。未知文件、未声明文件、缺失或无效表单和被另一文本格式遮蔽的头像不会进入角色包。确认界面会显示实际包含的头像和表单数量；偏好表单可能包含私人信息，分享前应直接打开 JSON 检查。
 
-导入会先检查格式版本、安全 ID、UTF-8、文件数量与总大小、角色卡结构、头像安全边界，以及每份表单是否由卡片明确声明。路径穿越、重复路径、未知文件、符号链接来源和同时包含两个头像的包都会被拒绝。整个角色先在个人目录内的临时位置完成构建和加载，再整体移动到正式位置；不会覆盖已有个人角色。同 ID 只有内置角色时，导入结果会成为个人覆盖副本。导入成功后可选择立即启用。
+导入会先检查格式版本、安全 ID、UTF-8/base64、文件数量与总大小、角色卡结构、头像安全边界，以及每份表单是否由卡片明确声明。路径穿越、重复路径、未知文件、符号链接来源、多个 PNG 或多个文本回退都会被拒绝。整个角色先在个人目录内的临时位置完成构建和加载，再整体移动到正式位置；不会覆盖已有个人角色。同 ID 只有内置角色时，导入结果会成为个人覆盖副本。导入成功后可选择立即启用。
 
-角色包最大 1 MiB、最多 66 个文件；其中角色卡最大 512 KiB，表单和头像继续沿用各自的 256 KiB 与 64 KiB 限制。导出目标和导入来源支持与头像导入相同的绝对路径、相对路径、`~/...`、`file://...`、引号和转义空格输入。导出不会覆盖已有文件。
+角色包最大 1 MiB、最多 66 个文件；其中角色卡最大 512 KiB，表单、文本头像和 PNG 分别沿用 256 KiB、64 KiB 和 512 KiB 限制。导出目标和导入来源支持与头像导入相同的绝对路径、相对路径、`~/...`、`file://...`、引号和转义空格输入。导出不会覆盖已有文件。
 
 ## 故障排查
 
@@ -210,6 +211,7 @@ Default: warm
 - `Current Mood ...`：检查 `Default:`、三级标题 preset ID 和对应正文。
 - `Forms: n/m available`：运行 `/incarnate status` 后检查缺失文件；表单路径必须留在角色目录内。
 - 彩色头像不显示：文件名应为 `avatar.ansi` 并位于对应角色目录；任意 ANSI 动画、光标控制或终端命令不会被支持。
+- PNG 头像不显示：确认同时安装 `pi-incarnate-ui`，并使用 Kitty、Ghostty、WezTerm 或 iTerm2 等已启用图片协议的终端；不支持时会自动使用 `avatar.ansi`/`avatar.txt` 回退。
 - 命令没有出现：开发时确认使用 `pi -e ./extensions/index.ts`；本地安装后可用 `pi list` 和 `pi config` 检查资源状态。
 - 项目本地扩展未加载：Pi 只从受信任项目自动加载 `.pi/extensions`；本项目的显式 `-e` 和本地包安装不依赖该目录。
 
@@ -228,7 +230,7 @@ src/persona.ts            有界人格 prompt 组合
 src/markdown.ts           识别 fenced code 的 Markdown 章节操作
 src/commands.ts           /incarnate 命令
 src/menu.ts               键盘导航菜单与角色卡编辑流程
-src/avatar.ts             ASCII/ANSI 头像读取与安全清理
+src/avatar.ts             PNG 校验、ASCII/ANSI 头像读取与安全清理
 src/avatar-manager.ts     头像路径解析、安全导入与移除
 src/form-editor.ts        偏好表单有界读取与原子编辑
 src/mood.ts               mood 预设解析和 prompt 片段

package/SECURITY.md

@@ -10,12 +10,13 @@ Pi extensions execute with the same system permissions as Pi. Review this packag
 - Character-card writes are validated before an atomic replacement, and copied character resources reject symbolic links and non-regular files.
 - Guided card edits replace only the selected top-level name or level-two section, reject ambiguous duplicates and structural heading injection, and pass through the same complete-card validation and atomic replacement as full edits.
 - Character lifecycle actions operate only on direct personal-character directories. Archive storage must be a real directory, moves refuse existing targets, and the menu exposes recovery instead of permanent deletion.
-- Portable character packages include only the card, one validated avatar, and available forms explicitly declared by that card. Imports reject unknown, duplicate, escaping, oversized, non-UTF-8, and symbolic-link inputs, build in a temporary personal directory, and never overwrite an existing personal character.
+- Portable character packages include only the card, one validated PNG primary avatar, one validated ANSI/TXT fallback, and available forms explicitly declared by that card. Binary PNG data uses explicit base64 encoding. Imports reject unknown, duplicate, escaping, oversized, malformed-encoding, non-UTF-8, and symbolic-link inputs, build in a temporary personal directory, and never overwrite an existing personal character.
 - Declared form paths must resolve to readable files inside their character directory.
 - Form contents are not loaded or cached during character activation or prompt composition. They are read only after an explicit `Manage preference forms` action, with UTF-8, regular-file, path-containment, and 256 KiB editor bounds.
 - Plain avatars have terminal control sequences removed. ANSI avatars use a strict SGR color-only allowlist; cursor movement, screen control, OSC, hyperlinks, and other escape sequences are removed. Both formats are byte-, line-, and width-limited, with a forced reset on every ANSI line.
-- Avatar imports reject symbolic-link and non-regular sources, invalid UTF-8, oversized files, and resources that would require display truncation. Only the sanitized result is written to a personal character directory.
-- The optional UI protocol broadcasts only bounded character metadata and already-sanitized avatar lines. It does not expose the complete character-card body, and unknown protocol claims are ignored.
+- PNG avatars are limited to 512 KiB, 2048 px per dimension, and 4,194,304 total pixels. Imports validate the PNG signature, IHDR fields, required chunks, and declared dimensions before preserving the binary bytes.
+- Avatar imports reject symbolic-link and non-regular sources, invalid UTF-8, malformed PNG data, oversized files, and text resources that would require display truncation. Only the validated or sanitized result is written to a personal character directory.
+- The optional UI protocol broadcasts only bounded character metadata, already-sanitized avatar lines, and validated PNG bytes encoded as base64. It does not expose the complete character-card body, and unknown protocol claims are ignored.
 - The personality layer is appended without replacing Pi's existing tool, permission, or safety instructions, and explicitly tells the model to preserve those boundaries.
 
 Do not include secrets in character cards or preference forms. A character can ask Pi to read an available declared form when relevant, so those files should contain only information you intend to expose to the active model.

package/characters/README.md

@@ -13,4 +13,4 @@ Every character directory must contain a UTF-8 `CHARACTER.md` with a level-one c
 
 Optional sections such as `Tools and Forms` and `Current Mood` are preserved verbatim and become part of the persona prompt. Declared forms and mood presets are validated by their dedicated loaders.
 
-An optional `avatar.txt` provides a plain UTF-8 avatar. An optional `avatar.ansi` takes precedence and may use only safe SGR foreground/background colors and resets. Both formats are limited to 64 KiB, 16 lines, and 48 visible columns.
+An optional `avatar.png` is the primary avatar on terminals with supported inline-image protocols. It is limited to 512 KiB, 2048 px per dimension, and 4,194,304 total pixels, with PNG structure and chunk checksums validated by the core extension. An optional `avatar.ansi` or `avatar.txt` provides the terminal-compatible fallback; ANSI takes precedence over plain text and may use only safe SGR foreground/background colors and resets. Both text formats are limited to 64 KiB, 16 lines, and 48 visible columns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-incarnate",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A character persona layer for Pi Agent",
   "author": "NandySun",
   "type": "module",

package/src/avatar-manager.ts

@@ -8,20 +8,35 @@ import {
   AVATAR_MAX_BYTES,
   AVATAR_MAX_COLUMNS,
   AVATAR_MAX_LINES,
+  AVATAR_PNG_MAX_BYTES,
   sanitizeAnsiAvatar,
   sanitizeAvatar,
+  validatePngAvatar,
+  AvatarLoadError,
 } from "./avatar.ts";
 import { CharacterEditError, resolvePersonalDirectory } from "./character-editor.ts";
 
-export type AvatarFileName = "avatar.ansi" | "avatar.txt";
+export type TextAvatarFileName = "avatar.ansi" | "avatar.txt";
+export type AvatarFileName = "avatar.png" | TextAvatarFileName;
 
-export interface PreparedAvatarImport {
-  filename: AvatarFileName;
+export interface PreparedTextAvatarImport {
+  kind: "text";
+  filename: TextAvatarFileName;
   content: string;
   width: number;
   height: number;
 }
 
+export interface PreparedPngAvatarImport {
+  kind: "png";
+  filename: "avatar.png";
+  content: Buffer;
+  width: number;
+  height: number;
+}
+
+export type PreparedAvatarImport = PreparedTextAvatarImport | PreparedPngAvatarImport;
+
 function stripWrappingQuotes(value: string): string {
   if (value.length < 2) return value;
   const first = value[0];
@@ -40,7 +55,7 @@ export function resolveAvatarSourcePath(input: string, cwd: string, userHome = h
   return resolveUserPath(input, cwd, userHome);
 }
 
-export function prepareAvatarContent(filename: AvatarFileName, raw: string): PreparedAvatarImport {
+export function prepareAvatarContent(filename: TextAvatarFileName, raw: string): PreparedTextAvatarImport {
   if (Buffer.byteLength(raw, "utf8") > AVATAR_MAX_BYTES) {
     throw new CharacterEditError(`Avatar exceeds the ${AVATAR_MAX_BYTES}-byte limit`);
   }
@@ -50,6 +65,7 @@ export function prepareAvatarContent(filename: AvatarFileName, raw: string): Pre
     throw new CharacterEditError(`Avatar must fit within ${AVATAR_MAX_COLUMNS} columns and ${AVATAR_MAX_LINES} lines`);
   }
   return {
+    kind: "text",
     filename,
     content: `${avatar.lines.join("\n")}\n`,
     width: avatar.lines.reduce((maximum, line) => Math.max(maximum, visibleWidth(line)), 0),
@@ -57,12 +73,31 @@ export function prepareAvatarContent(filename: AvatarFileName, raw: string): Pre
   };
 }
 
+export function preparePngAvatarContent(bytes: Uint8Array): PreparedPngAvatarImport {
+  try {
+    const image = validatePngAvatar(bytes);
+    return {
+      kind: "png",
+      filename: "avatar.png",
+      content: Buffer.from(bytes),
+      width: image.widthPx,
+      height: image.heightPx,
+    };
+  } catch (error) {
+    if (error instanceof AvatarLoadError) throw new CharacterEditError(error.message);
+    throw error;
+  }
+}
+
 export async function prepareAvatarImport(sourcePath: string): Promise<PreparedAvatarImport> {
   const extension = extname(sourcePath).toLowerCase();
   let filename: AvatarFileName;
+  let maximumBytes: number;
   if (extension === ".ansi") filename = "avatar.ansi";
   else if (extension === ".txt") filename = "avatar.txt";
-  else throw new CharacterEditError("Avatar file must end in .ansi or .txt");
+  else if (extension === ".png") filename = "avatar.png";
+  else throw new CharacterEditError("Avatar file must end in .png, .ansi, or .txt");
+  maximumBytes = filename === "avatar.png" ? AVATAR_PNG_MAX_BYTES : AVATAR_MAX_BYTES;
 
   let bytes: Buffer;
   try {
@@ -70,18 +105,20 @@ export async function prepareAvatarImport(sourcePath: string): Promise<PreparedA
     if (!info.isFile() || info.isSymbolicLink()) {
       throw new CharacterEditError(`Avatar source must be a regular file: ${sourcePath}`);
     }
-    if (info.size > AVATAR_MAX_BYTES) {
-      throw new CharacterEditError(`Avatar exceeds the ${AVATAR_MAX_BYTES}-byte limit: ${sourcePath}`);
+    if (info.size > maximumBytes) {
+      throw new CharacterEditError(`Avatar exceeds the ${maximumBytes}-byte limit: ${sourcePath}`);
     }
     bytes = await readFile(sourcePath);
-    if (bytes.byteLength > AVATAR_MAX_BYTES) {
-      throw new CharacterEditError(`Avatar exceeds the ${AVATAR_MAX_BYTES}-byte limit: ${sourcePath}`);
+    if (bytes.byteLength > maximumBytes) {
+      throw new CharacterEditError(`Avatar exceeds the ${maximumBytes}-byte limit: ${sourcePath}`);
     }
   } catch (error) {
     if (error instanceof CharacterEditError) throw error;
     throw new CharacterEditError(`Cannot read avatar source: ${sourcePath}`);
   }
 
+  if (filename === "avatar.png") return preparePngAvatarContent(bytes);
+
   let raw: string;
   try {
     raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
@@ -108,26 +145,31 @@ export async function installPersonalAvatar(
 ): Promise<string> {
   const directory = await resolvePersonalDirectory(personalRoot, id);
   const targetPath = join(directory, prepared.filename);
-  const alternatePath = join(directory, prepared.filename === "avatar.ansi" ? "avatar.txt" : "avatar.ansi");
+  const alternatePath = prepared.kind === "text"
+    ? join(directory, prepared.filename === "avatar.ansi" ? "avatar.txt" : "avatar.ansi")
+    : undefined;
   await assertReplaceable(targetPath);
-  await assertReplaceable(alternatePath);
+  if (alternatePath) await assertReplaceable(alternatePath);
 
   const nonce = crypto.randomUUID();
   const temporaryPath = join(directory, `.avatar-import-${nonce}.tmp`);
   const alternateBackup = join(directory, `.avatar-replaced-${nonce}.tmp`);
   let movedAlternate = false;
   try {
-    await writeFile(temporaryPath, prepared.content, { encoding: "utf8", flag: "wx" });
-    try {
-      await rename(alternatePath, alternateBackup);
-      movedAlternate = true;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    if (prepared.kind === "png") await writeFile(temporaryPath, prepared.content, { flag: "wx" });
+    else await writeFile(temporaryPath, prepared.content, { encoding: "utf8", flag: "wx" });
+    if (alternatePath) {
+      try {
+        await rename(alternatePath, alternateBackup);
+        movedAlternate = true;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
     }
     await rename(temporaryPath, targetPath);
     if (movedAlternate) await rm(alternateBackup, { force: true });
   } catch (error) {
-    if (movedAlternate) await rename(alternateBackup, alternatePath).catch(() => undefined);
+    if (movedAlternate && alternatePath) await rename(alternateBackup, alternatePath).catch(() => undefined);
     throw new CharacterEditError(`Cannot install avatar for ${id}: ${error instanceof Error ? error.message : "unknown error"}`);
   } finally {
     await rm(temporaryPath, { force: true });
@@ -138,7 +180,7 @@ export async function installPersonalAvatar(
 export async function removePersonalAvatars(personalRoot: string, id: string): Promise<number> {
   const directory = await resolvePersonalDirectory(personalRoot, id);
   let removed = 0;
-  for (const filename of ["avatar.ansi", "avatar.txt"] as const) {
+  for (const filename of ["avatar.png", "avatar.ansi", "avatar.txt"] as const) {
     const path = join(directory, filename);
     try {
       const info = await lstat(path);

package/src/avatar.ts

@@ -7,13 +7,31 @@ import type { Character } from "./character-loader.ts";
 export const AVATAR_MAX_COLUMNS = 48;
 export const AVATAR_MAX_LINES = 16;
 export const AVATAR_MAX_BYTES = 64 * 1024;
+export const AVATAR_PNG_MAX_BYTES = 512 * 1024;
+export const AVATAR_PNG_MAX_DIMENSION = 2048;
+export const AVATAR_PNG_MAX_PIXELS = 2048 * 2048;
 const ANSI_RESET = "\u001b[0m";
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const CRC32_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
+  let crc = value;
+  for (let bit = 0; bit < 8; bit += 1) crc = (crc & 1) === 1 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1;
+  return crc >>> 0;
+});
 const CSI_SEQUENCE_PATTERN = /\u001b\[[0-?]*[ -/]*[@-~]/g;
 const CONTROL_CHARACTER_PATTERN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
 
 export interface Avatar {
   lines: string[];
   truncated: boolean;
+  image?: AvatarImage;
+}
+
+export interface AvatarImage {
+  mimeType: "image/png";
+  data: string;
+  widthPx: number;
+  heightPx: number;
+  bytes: number;
 }
 
 export class AvatarLoadError extends Error {
@@ -88,6 +106,94 @@ function isWithin(parent: string, child: string): boolean {
   return pathFromParent !== ".." && !pathFromParent.startsWith(`..${sep}`);
 }
 
+function pngChunkCrc(buffer: Buffer, start: number, end: number): number {
+  let crc = 0xffffffff;
+  for (let index = start; index < end; index += 1) {
+    crc = CRC32_TABLE[(crc ^ buffer[index]!) & 0xff]! ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+export function validatePngAvatar(bytes: Uint8Array): AvatarImage {
+  const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (buffer.byteLength > AVATAR_PNG_MAX_BYTES) {
+    throw new AvatarLoadError(`avatar.png exceeds the ${AVATAR_PNG_MAX_BYTES}-byte limit`);
+  }
+  if (buffer.byteLength < 45 || !buffer.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) {
+    throw new AvatarLoadError("avatar.png is not a valid PNG file");
+  }
+
+  let offset = PNG_SIGNATURE.length;
+  let widthPx = 0;
+  let heightPx = 0;
+  let sawImageData = false;
+  let sawEnd = false;
+  while (offset + 12 <= buffer.byteLength) {
+    const chunkLength = buffer.readUInt32BE(offset);
+    const chunkEnd = offset + 12 + chunkLength;
+    if (chunkEnd > buffer.byteLength) throw new AvatarLoadError("avatar.png contains a truncated PNG chunk");
+    const chunkType = buffer.toString("ascii", offset + 4, offset + 8);
+    if (pngChunkCrc(buffer, offset + 4, offset + 8 + chunkLength) !== buffer.readUInt32BE(offset + 8 + chunkLength)) {
+      throw new AvatarLoadError(`avatar.png has an invalid ${chunkType} checksum`);
+    }
+    if (offset === PNG_SIGNATURE.length) {
+      if (chunkType !== "IHDR" || chunkLength !== 13) {
+        throw new AvatarLoadError("avatar.png must begin with a valid IHDR chunk");
+      }
+      widthPx = buffer.readUInt32BE(offset + 8);
+      heightPx = buffer.readUInt32BE(offset + 12);
+      const bitDepth = buffer[offset + 16]!;
+      const colorType = buffer[offset + 17]!;
+      const validDepths: Record<number, number[]> = {
+        0: [1, 2, 4, 8, 16],
+        2: [8, 16],
+        3: [1, 2, 4, 8],
+        4: [8, 16],
+        6: [8, 16],
+      };
+      if (
+        widthPx === 0 ||
+        heightPx === 0 ||
+        widthPx > AVATAR_PNG_MAX_DIMENSION ||
+        heightPx > AVATAR_PNG_MAX_DIMENSION ||
+        widthPx * heightPx > AVATAR_PNG_MAX_PIXELS
+      ) {
+        throw new AvatarLoadError(
+          `avatar.png must be at most ${AVATAR_PNG_MAX_DIMENSION}×${AVATAR_PNG_MAX_DIMENSION} pixels and ${AVATAR_PNG_MAX_PIXELS} total pixels`,
+        );
+      }
+      if (
+        !validDepths[colorType]?.includes(bitDepth) ||
+        buffer[offset + 18] !== 0 ||
+        buffer[offset + 19] !== 0 ||
+        (buffer[offset + 20] !== 0 && buffer[offset + 20] !== 1)
+      ) {
+        throw new AvatarLoadError("avatar.png has an unsupported PNG header");
+      }
+    } else if (chunkType === "IHDR") {
+      throw new AvatarLoadError("avatar.png contains multiple IHDR chunks");
+    }
+    if (chunkType === "IDAT") sawImageData = true;
+    if (chunkType === "IEND") {
+      if (chunkLength !== 0 || chunkEnd !== buffer.byteLength) {
+        throw new AvatarLoadError("avatar.png has an invalid IEND chunk");
+      }
+      sawEnd = true;
+      break;
+    }
+    offset = chunkEnd;
+  }
+  if (!sawImageData || !sawEnd) throw new AvatarLoadError("avatar.png is missing required PNG chunks");
+
+  return {
+    mimeType: "image/png",
+    data: buffer.toString("base64"),
+    widthPx,
+    heightPx,
+    bytes: buffer.byteLength,
+  };
+}
+
 export function sanitizeAvatar(raw: string, maxColumns = AVATAR_MAX_COLUMNS, maxLines = AVATAR_MAX_LINES): Avatar {
   const normalized = raw.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
   const lines = normalized.split("\n").map((line) => {
@@ -144,8 +250,39 @@ async function loadAvatarFile(character: Character, filename: string, allowAnsi:
   return allowAnsi ? sanitizeAnsiAvatar(raw) : sanitizeAvatar(raw);
 }
 
+async function loadPngAvatar(character: Character): Promise<AvatarImage | undefined> {
+  const filename = "avatar.png";
+  const avatarPath = join(character.directory, filename);
+  let canonicalAvatarPath: string;
+  try {
+    canonicalAvatarPath = await realpath(avatarPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw new AvatarLoadError(`Cannot inspect avatar: ${avatarPath}`);
+  }
+  if (!isWithin(character.directory, canonicalAvatarPath)) {
+    throw new AvatarLoadError(`Avatar path escapes the character directory: ${avatarPath}`);
+  }
+  let bytes: Buffer;
+  try {
+    bytes = await readFile(canonicalAvatarPath);
+  } catch {
+    throw new AvatarLoadError(`Cannot read avatar: ${avatarPath}`);
+  }
+  try {
+    return validatePngAvatar(bytes);
+  } catch (error) {
+    if (error instanceof AvatarLoadError) {
+      throw new AvatarLoadError(`${error.message}: ${avatarPath}`);
+    }
+    throw error;
+  }
+}
+
 export async function loadAvatar(character: Character): Promise<Avatar | undefined> {
+  const image = await loadPngAvatar(character);
   const ansi = await loadAvatarFile(character, "avatar.ansi", true);
-  if (ansi) return ansi;
-  return await loadAvatarFile(character, "avatar.txt", false);
+  const fallback = ansi ?? await loadAvatarFile(character, "avatar.txt", false);
+  if (!image) return fallback;
+  return { lines: fallback?.lines ?? [], truncated: fallback?.truncated ?? false, image };
 }

package/src/character-bundle.ts

@@ -5,6 +5,7 @@ import {
   installPersonalAvatar,
   prepareAvatarContent,
   prepareAvatarImport,
+  preparePngAvatarContent,
   type PreparedAvatarImport,
 } from "./avatar-manager.ts";
 import {
@@ -25,6 +26,7 @@ const CHARACTER_BUNDLE_MAX_FILES = 66;
 interface CharacterBundleFileV1 {
   path: string;
   content: string;
+  encoding?: "base64";
 }
 
 interface CharacterBundleDocumentV1 {
@@ -38,7 +40,7 @@ export interface PreparedCharacterBundle {
   id: string;
   name: string;
   card: string;
-  avatar?: PreparedAvatarImport;
+  avatars: PreparedAvatarImport[];
   forms: Array<{ path: string; content: string }>;
 }
 
@@ -132,6 +134,19 @@ async function bundleDocument(character: Character): Promise<{ document: Charact
   const files: CharacterBundleFileV1[] = [{ path: "CHARACTER.md", content: card }];
 
   let avatarIncluded = false;
+  for (const filename of ["avatar.png"] as const) {
+    const avatarPath = join(character.directory, filename);
+    try {
+      await lstat(avatarPath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw new CharacterEditError(`Cannot inspect avatar for export: ${avatarPath}`);
+    }
+    const avatar = await prepareAvatarImport(avatarPath);
+    if (avatar.kind !== "png") throw new CharacterEditError(`Unexpected avatar format: ${avatarPath}`);
+    files.push({ path: avatar.filename, content: avatar.content.toString("base64"), encoding: "base64" });
+    avatarIncluded = true;
+  }
   for (const filename of ["avatar.ansi", "avatar.txt"] as const) {
     const avatarPath = join(character.directory, filename);
     try {
@@ -141,6 +156,7 @@ async function bundleDocument(character: Character): Promise<{ document: Charact
       throw new CharacterEditError(`Cannot inspect avatar for export: ${avatarPath}`);
     }
     const avatar = await prepareAvatarImport(avatarPath);
+    if (avatar.kind !== "text") throw new CharacterEditError(`Unexpected avatar format: ${avatarPath}`);
     files.push({ path: avatar.filename, content: avatar.content });
     avatarIncluded = true;
     break;
@@ -219,6 +235,23 @@ export async function writeCharacterBundle(
   return summary;
 }
 
+function decodeBase64(value: string, path: string): Buffer {
+  if (value.length === 0 || value.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    throw new CharacterEditError(`Character bundle contains invalid base64 content: ${path}`);
+  }
+  const decoded = Buffer.from(value, "base64");
+  if (decoded.toString("base64") !== value) {
+    throw new CharacterEditError(`Character bundle contains non-canonical base64 content: ${path}`);
+  }
+  return decoded;
+}
+
+function bundleAvatarEntry(avatar: PreparedAvatarImport): CharacterBundleFileV1 {
+  return avatar.kind === "png"
+    ? { path: avatar.filename, content: avatar.content.toString("base64"), encoding: "base64" }
+    : { path: avatar.filename, content: avatar.content };
+}
+
 function validateBundleDocument(value: unknown): PreparedCharacterBundle {
   if (!isRecord(value) || value.format !== CHARACTER_BUNDLE_FORMAT || value.version !== CHARACTER_BUNDLE_VERSION) {
     throw new CharacterEditError("Unsupported character bundle format or version");
@@ -230,10 +263,15 @@ function validateBundleDocument(value: unknown): PreparedCharacterBundle {
     throw new CharacterEditError(`Character bundle must contain 1-${CHARACTER_BUNDLE_MAX_FILES} files`);
   }
 
-  const files = new Map<string, string>();
+  const files = new Map<string, CharacterBundleFileV1>();
   let contentBytes = 0;
   for (const entry of value.files) {
-    if (!isRecord(entry) || typeof entry.path !== "string" || typeof entry.content !== "string") {
+    if (
+      !isRecord(entry) ||
+      typeof entry.path !== "string" ||
+      typeof entry.content !== "string" ||
+      (entry.encoding !== undefined && entry.encoding !== "base64")
+    ) {
       throw new CharacterEditError("Character bundle contains an invalid file entry");
     }
     const path = normalizePortablePath(entry.path);
@@ -242,11 +280,13 @@ function validateBundleDocument(value: unknown): PreparedCharacterBundle {
     if (contentBytes > CHARACTER_BUNDLE_MAX_BYTES) {
       throw new CharacterEditError(`Character bundle content exceeds the ${CHARACTER_BUNDLE_MAX_BYTES}-byte limit`);
     }
-    files.set(path, entry.content);
+    files.set(path, { path, content: entry.content, ...(entry.encoding === "base64" ? { encoding: "base64" as const } : {}) });
   }
 
-  const card = files.get("CHARACTER.md");
-  if (card === undefined) throw new CharacterEditError("Character bundle is missing CHARACTER.md");
+  const cardEntry = files.get("CHARACTER.md");
+  if (cardEntry === undefined) throw new CharacterEditError("Character bundle is missing CHARACTER.md");
+  if (cardEntry.encoding !== undefined) throw new CharacterEditError("CHARACTER.md must use UTF-8 text content");
+  const card = cardEntry.content;
   if (byteLength(card) > CHARACTER_CARD_MAX_BYTES) {
     throw new CharacterEditError(`CHARACTER.md exceeds the ${CHARACTER_CARD_MAX_BYTES}-byte bundle limit`);
   }
@@ -261,15 +301,28 @@ function validateBundleDocument(value: unknown): PreparedCharacterBundle {
     }
   }
 
-  let avatar: PreparedAvatarImport | undefined;
+  const avatars: PreparedAvatarImport[] = [];
+  let textAvatarFound = false;
+  let pngAvatarFound = false;
   const forms: Array<{ path: string; content: string }> = [];
-  for (const [path, content] of files) {
+  for (const [path, entry] of files) {
     if (path === "CHARACTER.md") continue;
+    const { content, encoding } = entry;
+    if (path === "avatar.png") {
+      if (pngAvatarFound) throw new CharacterEditError("Character bundle may contain only one PNG avatar");
+      if (encoding !== "base64") throw new CharacterEditError("avatar.png must use base64 content");
+      avatars.push(preparePngAvatarContent(decodeBase64(content, path)));
+      pngAvatarFound = true;
+      continue;
+    }
     if (path === "avatar.ansi" || path === "avatar.txt") {
-      if (avatar) throw new CharacterEditError("Character bundle may contain only one avatar file");
-      avatar = prepareAvatarContent(path, content);
+      if (textAvatarFound) throw new CharacterEditError("Character bundle may contain only one text avatar fallback");
+      if (encoding !== undefined) throw new CharacterEditError(`${path} must use UTF-8 text content`);
+      avatars.push(prepareAvatarContent(path, content));
+      textAvatarFound = true;
       continue;
     }
+    if (encoding !== undefined) throw new CharacterEditError(`Character bundle text file must not use base64: ${path}`);
     if (!allowedForms.has(path)) {
       throw new CharacterEditError(`Character bundle contains an undeclared file: ${path}`);
     }
@@ -278,7 +331,7 @@ function validateBundleDocument(value: unknown): PreparedCharacterBundle {
     }
     forms.push({ path, content });
   }
-  return { id: value.id, name: parsed.name, card, avatar, forms };
+  return { id: value.id, name: parsed.name, card, avatars, forms };
 }
 
 export async function prepareCharacterBundleImport(sourcePath: string): Promise<PreparedCharacterBundle> {
@@ -303,7 +356,7 @@ export async function installCharacterBundle(
     id: bundle.id,
     files: [
       { path: "CHARACTER.md", content: bundle.card },
-      ...(bundle.avatar ? [{ path: bundle.avatar.filename, content: bundle.avatar.content }] : []),
+      ...bundle.avatars.map(bundleAvatarEntry),
       ...bundle.forms.map((form) => ({ path: form.path, content: form.content })),
     ],
   });
@@ -317,7 +370,7 @@ export async function installCharacterBundle(
     for (const form of validated.forms) {
       await savePersonalForm(stagingRoot, validated.id, form.path, form.content);
     }
-    if (validated.avatar) await installPersonalAvatar(stagingRoot, validated.id, validated.avatar);
+    for (const avatar of validated.avatars) await installPersonalAvatar(stagingRoot, validated.id, avatar);
     const staged = await loadCharacter(stagingRoot, validated.id);
     await rename(staged.directory, target);
     return await loadCharacter(canonicalRoot, validated.id);

package/src/menu.ts

@@ -391,7 +391,7 @@ async function manageAvatarFile(ctx: ExtensionCommandContext, dependencies: Inca
 
   try {
     if (action === "Import avatar file") {
-      const input = await ctx.ui.input("Avatar file", "path to a .ansi or .txt file; drag and drop is supported");
+      const input = await ctx.ui.input("Avatar file", "path to a .png, .ansi, or .txt file; drag and drop is supported");
       if (!input?.trim()) return;
       const sourcePath = resolveAvatarSourcePath(input, ctx.cwd);
       const prepared = await prepareAvatarImport(sourcePath);
@@ -399,7 +399,8 @@ async function manageAvatarFile(ctx: ExtensionCommandContext, dependencies: Inca
       if (!character) return;
       const targetPath = await installPersonalAvatar(personalRoot, character.id, prepared);
       await refreshEditedCharacter(ctx, dependencies, character);
-      ctx.ui.notify(`Avatar imported: ${prepared.width}×${prepared.height}\n${targetPath}`, "info");
+      const unit = prepared.kind === "png" ? "px" : "cells";
+      ctx.ui.notify(`Avatar imported: ${prepared.width}×${prepared.height} ${unit}\n${targetPath}`, "info");
       return;
     }
 
@@ -610,7 +611,7 @@ async function importCharacterBundle(
     const confirmed = await confirmMenu(
       ctx,
       "Import character package?",
-      `${bundle.name} (${bundle.id}) · Avatar: ${bundle.avatar ? "included" : "none"} · Forms: ${bundle.forms.length}. Existing personal characters are never overwritten.`,
+      `${bundle.name} (${bundle.id}) · Avatar: ${bundle.avatars.length > 0 ? "included" : "none"} · Forms: ${bundle.forms.length}. Existing personal characters are never overwritten.`,
     );
     if (!confirmed) return;
     const character = await installCharacterBundle(personalRoot, bundle);

package/src/ui-protocol.ts

@@ -26,6 +26,13 @@ export interface IncarnateUiStateV1 {
     width: number;
     height: number;
     truncated: boolean;
+    image?: {
+      mimeType: "image/png";
+      data: string;
+      widthPx: number;
+      heightPx: number;
+      bytes: number;
+    };
   };
 }
 
@@ -60,6 +67,7 @@ export function createUiStateSnapshot(
       width: avatar.lines.reduce((maximum, line) => Math.max(maximum, visibleWidth(line)), 0),
       height: avatar.lines.length,
       truncated: avatar.truncated,
+      ...(avatar.image ? { image: { ...avatar.image } } : {}),
     };
   }
   return snapshot;