pi-incarnate 0.1.0 → 0.3.0

package/src/avatar.ts

@@ -5,11 +5,33 @@ import { stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil
 import type { Character } from "./character-loader.ts";
 
 export const AVATAR_MAX_COLUMNS = 48;
-export const AVATAR_MAX_LINES = 12;
+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 {
@@ -19,33 +41,185 @@ export class AvatarLoadError extends Error {
   }
 }
 
+function isSafeSgr(sequence: string): boolean {
+  const match = sequence.match(/^\u001b\[([0-9;]*)m$/);
+  if (!match) return false;
+  const parameters = match[1] === "" ? [0] : match[1].split(";").map(Number);
+  if (parameters.some((value) => !Number.isInteger(value))) return false;
+  if (parameters.length === 1) {
+    const value = parameters[0]!;
+    return (
+      value === 0 ||
+      value === 39 ||
+      value === 49 ||
+      (value >= 30 && value <= 37) ||
+      (value >= 40 && value <= 47) ||
+      (value >= 90 && value <= 97) ||
+      (value >= 100 && value <= 107)
+    );
+  }
+  if (parameters.length === 3 && (parameters[0] === 38 || parameters[0] === 48) && parameters[1] === 5) {
+    return parameters[2]! >= 0 && parameters[2]! <= 255;
+  }
+  if (parameters.length === 5 && (parameters[0] === 38 || parameters[0] === 48) && parameters[1] === 2) {
+    return parameters.slice(2).every((value) => value >= 0 && value <= 255);
+  }
+  return false;
+}
+
+function preserveSafeSgr(raw: string): string {
+  const sequences: string[] = [];
+  const tokenized = raw
+    .replace(/[\uE000\uE001]/g, "")
+    .replace(CSI_SEQUENCE_PATTERN, (sequence) => {
+      if (!isSafeSgr(sequence)) return "";
+      const index = sequences.push(sequence) - 1;
+      return `\uE000${index}\uE001`;
+    });
+  return stripTerminalSequences(tokenized)
+    .replace(CONTROL_CHARACTER_PATTERN, "")
+    .replace(/\uE000(\d+)\uE001/g, (_token, index: string) => sequences[Number(index)] ?? "");
+}
+
+function isVisuallyBlank(line: string): boolean {
+  return stripTerminalSequences(line).trim() === "";
+}
+
+function limitAvatarLines(lines: string[], maxColumns: number, maxLines: number): Avatar {
+  let truncated = false;
+  const limited = lines.map((line) => {
+    if (visibleWidth(line) <= maxColumns) return line;
+    truncated = true;
+    return truncateToWidth(line, maxColumns, "…");
+  });
+  while (limited.length > 0 && isVisuallyBlank(limited[0]!)) limited.shift();
+  while (limited.length > 0 && isVisuallyBlank(limited.at(-1)!)) limited.pop();
+  if (limited.length > maxLines) {
+    limited.splice(maxLines);
+    truncated = true;
+  }
+  return { lines: limited, truncated };
+}
+
 function isWithin(parent: string, child: string): boolean {
   const pathFromParent = relative(parent, child);
   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");
-  let truncated = false;
-  let lines = normalized.split("\n").map((line) => {
+  const lines = normalized.split("\n").map((line) => {
     const safe = stripTerminalSequences(line.replace(/\t/g, "    "))
-      .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "")
+      .replace(CONTROL_CHARACTER_PATTERN, "")
       .trimEnd();
-    if (visibleWidth(safe) <= maxColumns) return safe;
-    truncated = true;
-    return truncateToWidth(safe, maxColumns, "…");
+    return safe;
   });
-  while (lines[0] === "") lines.shift();
-  while (lines.at(-1) === "") lines.pop();
-  if (lines.length > maxLines) {
-    lines = lines.slice(0, maxLines);
-    truncated = true;
-  }
-  return { lines, truncated };
+  return limitAvatarLines(lines, maxColumns, maxLines);
 }
 
-export async function loadAvatar(character: Character): Promise<Avatar | undefined> {
-  const avatarPath = join(character.directory, "avatar.txt");
+export function sanitizeAnsiAvatar(
+  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) => {
+    const safe = preserveSafeSgr(line.replace(/\t/g, "    "));
+    return safe.includes("\u001b[") ? `${safe}${ANSI_RESET}` : safe;
+  });
+  return limitAvatarLines(lines, maxColumns, maxLines);
+}
+
+async function loadAvatarFile(character: Character, filename: string, allowAnsi: boolean): Promise<Avatar | undefined> {
+  const avatarPath = join(character.directory, filename);
   let canonicalAvatarPath: string;
   try {
     canonicalAvatarPath = await realpath(avatarPath);
@@ -63,18 +237,52 @@ export async function loadAvatar(character: Character): Promise<Avatar | undefin
   } catch {
     throw new AvatarLoadError(`Cannot read avatar: ${avatarPath}`);
   }
+  if (bytes.byteLength > AVATAR_MAX_BYTES) {
+    throw new AvatarLoadError(`${filename} exceeds the ${AVATAR_MAX_BYTES}-byte limit: ${avatarPath}`);
+  }
 
   let raw: string;
   try {
     raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
   } catch {
-    throw new AvatarLoadError(`avatar.txt is not valid UTF-8: ${avatarPath}`);
+    throw new AvatarLoadError(`${filename} is not valid UTF-8: ${avatarPath}`);
+  }
+  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;
   }
-  return sanitizeAvatar(raw);
 }
 
-export function renderAvatarWidget(character: Character, mood: string | undefined, avatar: Avatar | undefined): string[] {
-  const moodLabel = mood ? ` · mood: ${mood}` : "";
-  const header = truncateToWidth(`pi-incarnate · ${character.name}${moodLabel}`, AVATAR_MAX_COLUMNS, "…");
-  return [header, ...(avatar?.lines ?? [])];
+export async function loadAvatar(character: Character): Promise<Avatar | undefined> {
+  const image = await loadPngAvatar(character);
+  const ansi = await loadAvatarFile(character, "avatar.ansi", true);
+  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

@@ -0,0 +1,383 @@
+import { link, lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+
+import {
+  installPersonalAvatar,
+  prepareAvatarContent,
+  prepareAvatarImport,
+  preparePngAvatarContent,
+  type PreparedAvatarImport,
+} from "./avatar-manager.ts";
+import {
+  CharacterEditError,
+  createPersonalCharacter,
+} from "./character-editor.ts";
+import { FORM_MAX_BYTES, readFormDraft, savePersonalForm } from "./form-editor.ts";
+import { parseFormDeclarations } from "./forms.ts";
+import { isCharacterId, loadCharacter, parseCharacterCard, type Character } from "./character-loader.ts";
+
+export const CHARACTER_BUNDLE_FORMAT = "pi-incarnate-character";
+export const CHARACTER_BUNDLE_VERSION = 1;
+export const CHARACTER_BUNDLE_SUFFIX = ".pi-character.json";
+export const CHARACTER_BUNDLE_MAX_BYTES = 1024 * 1024;
+const CHARACTER_CARD_MAX_BYTES = 512 * 1024;
+const CHARACTER_BUNDLE_MAX_FILES = 66;
+
+interface CharacterBundleFileV1 {
+  path: string;
+  content: string;
+  encoding?: "base64";
+}
+
+interface CharacterBundleDocumentV1 {
+  format: typeof CHARACTER_BUNDLE_FORMAT;
+  version: typeof CHARACTER_BUNDLE_VERSION;
+  id: string;
+  files: CharacterBundleFileV1[];
+}
+
+export interface PreparedCharacterBundle {
+  id: string;
+  name: string;
+  card: string;
+  avatars: PreparedAvatarImport[];
+  forms: Array<{ path: string; content: string }>;
+}
+
+export interface CharacterBundleSummary {
+  id: string;
+  name: string;
+  avatarIncluded: boolean;
+  formsIncluded: number;
+  formsDeclared: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function byteLength(value: string): number {
+  return Buffer.byteLength(value, "utf8");
+}
+
+function normalizeDeclaredFormPath(value: string): string {
+  if (
+    !value ||
+    value.includes("\\") ||
+    value.includes("\0") ||
+    isAbsolute(value) ||
+    posix.isAbsolute(value) ||
+    /^[a-zA-Z]:/.test(value)
+  ) {
+    throw new CharacterEditError(`Invalid character bundle path: ${value}`);
+  }
+  const normalized = posix.normalize(value);
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    throw new CharacterEditError(`Invalid character bundle path: ${value}`);
+  }
+  return normalized;
+}
+
+function normalizePortablePath(value: string): string {
+  const normalized = normalizeDeclaredFormPath(value);
+  if (normalized !== value) throw new CharacterEditError(`Invalid character bundle path: ${value}`);
+  return normalized;
+}
+
+function portableRelativePath(root: string, target: string): string {
+  const value = relative(root, target).split(sep).join("/");
+  return normalizePortablePath(value);
+}
+
+function assertBundleTarget(path: string): void {
+  if (!path.toLowerCase().endsWith(CHARACTER_BUNDLE_SUFFIX)) {
+    throw new CharacterEditError(`Character bundle must end in ${CHARACTER_BUNDLE_SUFFIX}`);
+  }
+}
+
+async function assertMissing(path: string, message: string): Promise<void> {
+  try {
+    await lstat(path);
+    throw new CharacterEditError(message);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+async function readRegularUtf8(path: string, maximumBytes: number, label: string): Promise<string> {
+  let bytes: Buffer;
+  try {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      throw new CharacterEditError(`${label} must be a regular file: ${path}`);
+    }
+    if (info.size > maximumBytes) throw new CharacterEditError(`${label} exceeds the ${maximumBytes}-byte limit`);
+    bytes = await readFile(path);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    throw new CharacterEditError(`Cannot read ${label.toLowerCase()}: ${path}`);
+  }
+  if (bytes.byteLength > maximumBytes) throw new CharacterEditError(`${label} exceeds the ${maximumBytes}-byte limit`);
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new CharacterEditError(`${label} is not valid UTF-8: ${path}`);
+  }
+}
+
+async function bundleDocument(character: Character): Promise<{ document: CharacterBundleDocumentV1; summary: CharacterBundleSummary }> {
+  const card = `${character.markdown.trimEnd()}\n`;
+  if (byteLength(card) > CHARACTER_CARD_MAX_BYTES) {
+    throw new CharacterEditError(`CHARACTER.md exceeds the ${CHARACTER_CARD_MAX_BYTES}-byte bundle limit`);
+  }
+  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 {
+      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 !== "text") throw new CharacterEditError(`Unexpected avatar format: ${avatarPath}`);
+    files.push({ path: avatar.filename, content: avatar.content });
+    avatarIncluded = true;
+    break;
+  }
+
+  const includedForms = new Set<string>();
+  for (const form of character.forms) {
+    if (form.status !== "available") continue;
+    const draft = await readFormDraft(character.directory, form.declaredPath, form.label);
+    if (!draft.exists) continue;
+    const path = portableRelativePath(character.directory, draft.path);
+    if (includedForms.has(path)) continue;
+    includedForms.add(path);
+    files.push({ path, content: draft.content });
+  }
+
+  if (files.length > CHARACTER_BUNDLE_MAX_FILES) {
+    throw new CharacterEditError(`Character bundle exceeds the ${CHARACTER_BUNDLE_MAX_FILES}-file limit`);
+  }
+  const document: CharacterBundleDocumentV1 = {
+    format: CHARACTER_BUNDLE_FORMAT,
+    version: CHARACTER_BUNDLE_VERSION,
+    id: character.id,
+    files,
+  };
+  const encoded = `${JSON.stringify(document, null, 2)}\n`;
+  if (byteLength(encoded) > CHARACTER_BUNDLE_MAX_BYTES) {
+    throw new CharacterEditError(`Character bundle exceeds the ${CHARACTER_BUNDLE_MAX_BYTES}-byte limit`);
+  }
+  return {
+    document,
+    summary: {
+      id: character.id,
+      name: character.name,
+      avatarIncluded,
+      formsIncluded: includedForms.size,
+      formsDeclared: character.forms.length,
+    },
+  };
+}
+
+export async function writeCharacterBundle(
+  character: Character,
+  targetPath: string,
+): Promise<CharacterBundleSummary> {
+  assertBundleTarget(targetPath);
+  const requestedTarget = resolve(targetPath);
+  const parent = dirname(requestedTarget);
+  let canonicalParent: string;
+  try {
+    const info = await lstat(parent);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      throw new CharacterEditError(`Bundle destination parent must be a real directory: ${parent}`);
+    }
+    canonicalParent = await realpath(parent);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    throw new CharacterEditError(`Cannot access bundle destination directory: ${parent}`);
+  }
+  const target = join(canonicalParent, basename(requestedTarget));
+  await assertMissing(target, `Character bundle already exists: ${target}`);
+  const { document, summary } = await bundleDocument(character);
+  const temporaryPath = join(canonicalParent, `.incarnate-export-${crypto.randomUUID()}.tmp`);
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(document, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    await link(temporaryPath, target);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      throw new CharacterEditError(`Character bundle already exists: ${target}`);
+    }
+    if (error instanceof CharacterEditError) throw error;
+    throw new CharacterEditError(`Cannot write character bundle: ${target}`);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+  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");
+  }
+  if (typeof value.id !== "string" || !isCharacterId(value.id)) {
+    throw new CharacterEditError("Character bundle has an invalid id");
+  }
+  if (!Array.isArray(value.files) || value.files.length === 0 || value.files.length > CHARACTER_BUNDLE_MAX_FILES) {
+    throw new CharacterEditError(`Character bundle must contain 1-${CHARACTER_BUNDLE_MAX_FILES} files`);
+  }
+
+  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" ||
+      (entry.encoding !== undefined && entry.encoding !== "base64")
+    ) {
+      throw new CharacterEditError("Character bundle contains an invalid file entry");
+    }
+    const path = normalizePortablePath(entry.path);
+    if (files.has(path)) throw new CharacterEditError(`Character bundle contains a duplicate path: ${path}`);
+    contentBytes += byteLength(entry.content);
+    if (contentBytes > CHARACTER_BUNDLE_MAX_BYTES) {
+      throw new CharacterEditError(`Character bundle content exceeds the ${CHARACTER_BUNDLE_MAX_BYTES}-byte limit`);
+    }
+    files.set(path, { path, content: entry.content, ...(entry.encoding === "base64" ? { encoding: "base64" as const } : {}) });
+  }
+
+  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`);
+  }
+  const parsed = parseCharacterCard(card, "CHARACTER.md");
+  const allowedForms = new Set<string>();
+  for (const declaration of parseFormDeclarations(card)) {
+    try {
+      const path = normalizeDeclaredFormPath(declaration.declaredPath);
+      if (extname(path).toLowerCase() === ".md" && path !== "CHARACTER.md") allowedForms.add(path);
+    } catch {
+      // Invalid declarations remain unavailable after import and cannot authorize bundled files.
+    }
+  }
+
+  const avatars: PreparedAvatarImport[] = [];
+  let textAvatarFound = false;
+  let pngAvatarFound = false;
+  const forms: Array<{ path: string; content: string }> = [];
+  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 (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}`);
+    }
+    if (byteLength(content) > FORM_MAX_BYTES) {
+      throw new CharacterEditError(`Form exceeds the ${FORM_MAX_BYTES}-byte limit: ${path}`);
+    }
+    forms.push({ path, content });
+  }
+  return { id: value.id, name: parsed.name, card, avatars, forms };
+}
+
+export async function prepareCharacterBundleImport(sourcePath: string): Promise<PreparedCharacterBundle> {
+  assertBundleTarget(sourcePath);
+  const content = await readRegularUtf8(sourcePath, CHARACTER_BUNDLE_MAX_BYTES, "Character bundle");
+  let document: unknown;
+  try {
+    document = JSON.parse(content);
+  } catch {
+    throw new CharacterEditError("Character bundle is not valid JSON");
+  }
+  return validateBundleDocument(document);
+}
+
+export async function installCharacterBundle(
+  personalRoot: string,
+  bundle: PreparedCharacterBundle,
+): Promise<Character> {
+  const validated = validateBundleDocument({
+    format: CHARACTER_BUNDLE_FORMAT,
+    version: CHARACTER_BUNDLE_VERSION,
+    id: bundle.id,
+    files: [
+      { path: "CHARACTER.md", content: bundle.card },
+      ...bundle.avatars.map(bundleAvatarEntry),
+      ...bundle.forms.map((form) => ({ path: form.path, content: form.content })),
+    ],
+  });
+  await mkdir(personalRoot, { recursive: true });
+  const canonicalRoot = await realpath(personalRoot);
+  const target = join(canonicalRoot, validated.id);
+  await assertMissing(target, `A personal character already exists: ${validated.id}`);
+  const stagingRoot = await mkdtemp(join(canonicalRoot, ".incarnate-import-"));
+  try {
+    await createPersonalCharacter(stagingRoot, validated.id, validated.card);
+    for (const form of validated.forms) {
+      await savePersonalForm(stagingRoot, validated.id, form.path, form.content);
+    }
+    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);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    throw new CharacterEditError(`Cannot install character bundle: ${error instanceof Error ? error.message : "unknown error"}`);
+  } finally {
+    await rm(stagingRoot, { recursive: true, force: true });
+  }
+}