API 参考

核心函数

validateExpression(input)

验证表达式对象。返回 { ok: true, value } 或 { ok: false, errors }。

normalizeExpression(input)

用默认值填充缺失字段并钳位超出范围的值。总是返回完整的 EmotileExpression。

repairExpression(input)

修复无效形状，钳位数值，填充缺失字段。返回 { value, warnings }。

renderExpression(expression)

将归一化表达式渲染为 PixelFrame——一个具有 width、height 和 pixels[] 的纯数据结构。

mutateExpression(expression, options)

生成表达式的确定性变化。

• options.seed：用于可重现性的字符串或数字
• options.amount：0–1 变化强度

renderPixelFrameToASCII(frame)

将 PixelFrame 转换为用于终端调试输出的 ASCII 字符串。

tickExpression(expression, tick)

使用显式整数 tick 将 motion 字段应用到表达式。确定性的——相同的表达式和 tick 总是产生相同的输出。无定时器或副作用。返回可渲染的新表达式。

v0.2 中活跃的 motion 字段：

• blink —— 周期性闭眼
• breath —— 正弦波 squash 和垂直偏移
• shake —— 眼睛和嘴巴的正弦/余弦偏移
• jitter —— 确定性随机微动
• glitch —— 偶尔的确定性随机形状交换

buildExpression(options?)

从高阶语义选项构建合法、归一化的表达式。所有数值自动钳位；无效枚举选项回退到安全默认值。

示例：

const expr = buildExpression({
  eyeShape: "arc",
  mouthShape: "smile",
  curve: 0.5,
  marks: ["heart"],
});

AGENT_GUIDANCE

AI Agent 生成表达式时推荐的安全范围和约束。包括默认位置、安全数值范围和最大推荐标记数。

MINIMAL_EXPRESSION

一个可安全复制的起始模板，包含所有必填字段，省略可选字段。可直接传递给 validateExpression。

COMMON_AGENT_MISTAKES

常见生成错误目录及 repairExpression 的修复方式。用于自我纠正 Agent 输出。

类型

关键导出类型：

• EmotileExpression —— 顶层表达式对象
• PixelFrame —— 渲染输出
• Pixel —— 具有 x、y、color 的单个像素
• ValidationResult<T> —— 验证结果类型
• RepairResult —— 修复结果类型

主题 / 调色板

applyTheme(frame, options?)

使用外部主题将 PixelFrame 中的语义颜色映射为具体十六进制颜色。返回包含字符串颜色像素和解析后 theme 对象的 ThemedFrame。

import { applyTheme, renderExpression } from "@yangyus8/emotile";

const frame = renderExpression(expr);
const themed = applyTheme(frame, { theme: { primary: "#3b82f6", accent: "#f59e0b" } });

DEFAULT_THEME

默认调色板映射：

• primary: #1a1a2e
• accent: #e94560
• shadow: #533483
• background: #ffffff

normalizeTheme(theme?)

用默认值填充缺失的调色板键，并将无效的十六进制字符串回退。

SVG 渲染器

renderPixelFrameToSVG(frame, options?)

将 PixelFrame 转换为确定性 SVG 字符串。无 DOM、Canvas 或浏览器依赖。

选项：

• pixelSize：SVG 单位中的像素大小（默认 10）
• theme：可选自定义调色板
• background：是否填充背景（默认 false）
• classPrefix：CSS 类前缀（默认 "emotile"）

const svg = renderPixelFrameToSVG(frame, { pixelSize: 20, background: true });

JSON Schema

EMOTILE_EXPRESSION_SCHEMA

描述当前表达式格式的人工维护 JSON Schema 对象。

getExpressionSchema()

返回 Schema 的深拷贝。用于 Agent 结构化输出约束。

import { getExpressionSchema } from "@yangyus8/emotile";
const schema = getExpressionSchema();

CLI

全局安装或通过 npx 使用：

npx @yangyus8/emotile validate expr.json
npx @yangyus8/emotile repair expr.json
npx @yangyus8/emotile preview expr.json
npx @yangyus8/emotile render svg expr.json

命令：

• validate <file> —— 校验表达式 JSON，合法退出 0，不合法退出 1
• repair <file> —— 修复表达式并输出 JSON 到 stdout
• preview <file> —— 渲染 ASCII 预览
• render svg <file> —— 渲染 SVG 输出
• help —— 显示用法

退出码：0 成功，1 无效输入、错误或未知命令。

模式常量

从 schema 导出：

• FACE_SHAPES, EYE_SHAPES, MOUTH_SHAPES, MARK_TYPES
• DEFAULT_EXPRESSION, DEFAULT_CANVAS 等