cortico-world-ellen-voice 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,10 +1,23 @@
 # Changelog
 
-## 0.2.1
-
-- PNG 解码补齐灰度+透明（colorType 4），之前这类截图会直接报「不支持的颜色类型 4」。
-- 修正 0.2.0 教程里没提到的导出建议：Photoshop「导出为 PNG-24」或「另存为 PNG」都可，不要用 8 位索引色+透明。
-
+## 0.2.2
+
+- 修好形象包加载失败：0.2.0/0.2.1 装出来的包缺 `figure.js`（figure.json 的 `entry` 指向它），
+  Coopanion 一 import 就报错、静默退回默认角色。现在模板带上 `template/figure.js`，
+  安装时原样拷进包，并在写文件前校验入口文件存在（缺了直接报错，不再装出半个包）。
+- 覆盖安装先整包删除再写：之前只写不删，上一版多出来的文件（含旧 figure.js、旧贴图）会留在包里。
+- 拒绝内置形象 id（`coo`、`whale`）：这类包会被内置形象盖住，永远选不中，现在直接报错。
+- 模板元信息改成通用文案：不再把原作者的署名、角色介绍写进别人生成的包。
+- 超长文字按 emoji 边界截断：之前硬切会把 emoji 切成孤立代理，合成后出现乱码方块。
+- OneBot 连接被对端立刻断开时立即报错（之前要等满 30 秒才超时）。
+- TTS 返回非音频 content-type 时直接报错（避免把「HTTP 200 的错误网页」当成语音）。
+- `describe.json` 补上 `ellen_install_figure`，之前那里只有两个工具。
+
+## 0.2.1
+
+- PNG 解码补齐灰度+透明（colorType 4），之前这类截图会直接报「不支持的颜色类型 4」。
+- 修正 0.2.0 教程里没提到的导出建议：Photoshop「导出为 PNG-24」或「另存为 PNG」都可，不要用 8 位索引色+透明。
+
 ## 0.2.0
 
 - 新增 `ellen_install_figure`：把一张透明底 PNG 立绘装成 Coopanion 形象包（自动生成 figure.json、

package/README.md

@@ -23,13 +23,16 @@ TTS 代理可以是任何返回音频字节的 HTTP 服务：GPT-SoVITS 微调
 - **ellen_install_figure** `{ path, id, name, overwrite? }`：把一张**透明底 PNG** 立绘装成形象包。
   装出来的包放在 `data\home\companion\data\figures\<id>\`，装完在「装扮」页就能选。
   做法是把图等比缩到 847×859 的画布，骨架贴图全部写成透明占位——所以是静态立绘，不会换姿势。
+  包里会带一份入口脚本 `figure.js`（模板 `template/figure.js`），Coopanion 靠它把这张图挂到骨架上；
+  少了它，形象会被判为加载失败、静默退回默认角色。`overwrite` 覆盖时会先把旧包整个删掉再写，
+  不会把上一版的文件留在里面。`coo`、`whale` 是内置形象的 id，装成同名包永远不会被选中，工具会直接拒绝。
 
 语言缺省 `auto`，支持 `zh` / `ko` / `en` / `ja`。
 
 ## 关于形象
 
-本扩展**不附带任何角色美术**。`template/` 里只有两份 JSON 和一份贴图清单，没有图；
-立绘由使用者自己提供（自绘、委托画师，或按所在地区的同人规则使用官方素材——后者请自行确认授权）。
+本扩展**不附带任何角色美术**。`template/` 里只有两份 JSON、一份贴图清单和入口脚本 `figure.js`
+（只画你给的那张图，本身不含任何画作），立绘由使用者自己提供（自绘、委托画师，或按所在地区的同人规则使用官方素材——后者请自行确认授权）。
 
 白底图需要先抠成透明底再喂给 `ellen_install_figure`，工具不替你做抠图。
 

package/describe.json

@@ -57,6 +57,38 @@
         "zh": "合成语音并直接以语音条发到 QQ 私聊或群。",
         "en": "Synthesise speech and send it as a voice bar to QQ."
       }
+    },
+    {
+      "name": "ellen_install_figure",
+      "description": "Install a transparent-background PNG as a Coopanion figure pack (writes figure.json, model.json, the texture placeholders and the entry script figure.js). The pack then shows up in Coopanion's dress-up list. The extension ships no character art: the image comes from the user, and it must be a transparent PNG — cut the background out first.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Absolute path of the figure PNG."
+          },
+          "id": {
+            "type": "string",
+            "description": "Pack id: lowercase letters and digits, for example ellen."
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name, for example Ellen Joe."
+          },
+          "overwrite": {
+            "type": "boolean",
+            "description": "Replace the existing pack with the same id."
+          }
+        },
+        "required": ["path", "id", "name"],
+        "additionalProperties": false
+      },
+      "tags": ["setup"],
+      "summary": {
+        "zh": "把一张透明底 PNG 立绘装成 Coopanion 形象包。",
+        "en": "Turns a transparent-background PNG into a Coopanion figure pack."
+      }
     }
   ],
   "events": [

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "cortico-world-ellen-voice",
-    "version":  "0.2.1",
+    "version":  "0.2.2",
     "type":  "module",
     "description":  "Ellen Joe voice world for Coopanion: speak through a local GPT-SoVITS service, deliver voice bars to QQ, and install a figure pack from your own PNG",
     "author":  "deepseek study",

package/src/figure-pack.ts

@@ -1,17 +1,21 @@
 /**
  * 形象包生成器：把用户给的一张透明底 PNG 变成 Coopanion 能读的 figure 包。
  *
- * 包的结构照抄本目录 template/（figure.json、model.json、textures.json 里列的骨架贴图名称），
- * 其中 tex/figure.png 换成用户那张图，其余贴图写成 1×1 透明像素——骨架还在，但只看得见图本身。
+ * 包的结构照抄本目录 template/（figure.json、model.json、textures.json 里列的骨架贴图名称，
+ * 以及 figure.json 的 entry 指名的入口脚本 figure.js），其中 tex/figure.png 换成用户那张图，
+ * 其余贴图写成 1×1 透明像素——骨架还在，但只看得见图本身。
  * 扩展不附带任何角色美术，图由使用者自己提供。
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { blankPng, decodePng, encodePng, fitIntoCanvas } from './png.ts';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
+/** Coopanion 自带、按 id 优先返回的内置形象：占用同名 id 装出来的包永远不会被显示。 */
+const BUILTIN_IDS = new Set(['coo', 'whale']);
+
 /** 骨架画布尺寸，与模板里的 model.view（268×272）× 3.16 像素单位对齐。 */
 const CANVAS = { width: 847, height: 859 };
 const THUMB = 144;
@@ -32,6 +36,8 @@ export interface InstallOptions {
 export interface InstallResult {
   dir: string;
   files: number;
+  /** 写进包里的入口模块（figure.json 的 entry），通常是 figure.js。 */
+  entry: string;
   canvas: { width: number; height: number };
   sourceSize: { width: number; height: number };
 }
@@ -44,7 +50,22 @@ function templateDir(): string {
   for (const dir of candidates) {
     if (existsSync(join(dir, 'figure.json'))) return dir;
   }
-  throw new Error('扩展缺少 template/（figure.json、model.json、textures.json）');
+  throw new Error('扩展缺少 template/（figure.json、model.json、textures.json、figure.js）');
+}
+
+/**
+ * figure.json 的入口模块：Coopanion 会 `import(entry)` 再取 `export` 指名的工厂函数。
+ * 这个文件必须真的写进包里——0.2.1 及之前漏了它，装出来的形象包一律加载失败
+ * （日志 `形象包没加载`、聊天里 `[figure] … 没能显示出来`），自动退回默认角色。
+ */
+function entryOf(figureJson: Record<string, unknown>): string {
+  const raw = figureJson.entry;
+  const entry = typeof raw === 'string' ? raw.trim() : '';
+  if (!entry) throw new Error('模板 figure.json 缺少 entry（应指向 figure.js）');
+  if (entry.startsWith('/') || entry.includes('..') || /^[a-z][a-z0-9+.-]*:/i.test(entry)) {
+    throw new Error(`模板 figure.json 的 entry 不是包内相对路径：${entry}`);
+  }
+  return entry;
 }
 
 function readJson<T>(path: string): T {
@@ -61,6 +82,9 @@ export function normalizeId(raw: string): string {
 
 export function installFigure(options: InstallOptions): InstallResult {
   const id = normalizeId(options.id);
+  if (BUILTIN_IDS.has(id)) {
+    throw new Error(`「${id}」是 Coopanion 内置形象的 id：装上去也会被内置的盖住、永远选不中，换一个 id 吧`);
+  }
   const name = String(options.name ?? '').trim() || id;
   const sourcePath = resolve(options.source);
   if (!existsSync(sourcePath)) throw new Error(`找不到图片：${sourcePath}`);
@@ -70,8 +94,12 @@ export function installFigure(options: InstallOptions): InstallResult {
   const thumb = fitIntoCanvas(sourceImage, THUMB, THUMB, 0.92);
 
   const packDir = join(options.figuresDir, id);
-  if (existsSync(packDir) && !options.overwrite) {
-    throw new Error(`形象包已存在：${packDir}（overwrite=true 可覆盖）`);
+  if (existsSync(packDir)) {
+    if (!options.overwrite) {
+      throw new Error(`形象包已存在：${packDir}（overwrite=true 可覆盖）`);
+    }
+    // 覆盖要整包重来：只写不删会把上一版多出来的文件（含旧 figure.js）留在包里
+    rmSync(packDir, { recursive: true, force: true });
   }
 
   const tpl = templateDir();
@@ -79,6 +107,13 @@ export function installFigure(options: InstallOptions): InstallResult {
   const modelJson = readJson<Record<string, unknown>>(join(tpl, 'model.json'));
   const textures = readJson<string[]>(join(tpl, 'textures.json'));
 
+  // 入口模块先查一遍：模板缺 figure.js 时要在写文件之前就报错，别留下半个包
+  const entry = entryOf(figureJson);
+  const entrySource = join(tpl, entry);
+  if (!existsSync(entrySource)) {
+    throw new Error(`模板缺少入口模块 ${entry}（${entrySource}）：装出来的形象包会加载失败`);
+  }
+
   const thumbRel = `thumbs/${id}.png`;
   figureJson.id = id;
   figureJson.name = { zh: name, en: name };
@@ -114,6 +149,11 @@ export function installFigure(options: InstallOptions): InstallResult {
   files += 1;
   writeFileSync(join(packDir, thumbRel), encodePng(thumb));
   files += 1;
+  // 入口模块原样拷进包：它是 Coopanion 真正要 import 的那份代码
+  const entryTarget = join(packDir, entry);
+  mkdirSync(dirname(entryTarget), { recursive: true });
+  writeFileSync(entryTarget, readFileSync(entrySource));
+  files += 1;
   writeFileSync(join(packDir, 'figure.json'), JSON.stringify(figureJson, null, 2), 'utf8');
   writeFileSync(join(packDir, 'model.json'), JSON.stringify(modelJson), 'utf8');
   files += 2;
@@ -121,6 +161,7 @@ export function installFigure(options: InstallOptions): InstallResult {
   return {
     dir: packDir,
     files,
+    entry,
     canvas: CANVAS,
     sourceSize: { width: sourceImage.width, height: sourceImage.height },
   };

package/src/world.ts

@@ -222,7 +222,7 @@ export class EllenVoiceWorld implements World {
             `[形象已安装] ${name}（id=${id}）`,
             `目录：${result.dir}`,
             `源图：${result.sourceSize.width}×${result.sourceSize.height} → 画布 ${result.canvas.width}×${result.canvas.height}`,
-            `写入 ${result.files} 个文件（骨架贴图全部为透明占位）。`,
+            `写入 ${result.files} 个文件（含入口脚本 ${result.entry}，骨架贴图全部为透明占位）。`,
             '',
             '下一步：打开「装扮」页刷新，形象列表里就会出现它；如果已经打开着，切走再切回以重新读盘。',
             '说明：这是静态贴图，不会换姿势；人物大小沿用形象包里的画布比例。',
@@ -250,7 +250,11 @@ export class EllenVoiceWorld implements World {
     const text = typeof raw === 'string' ? raw.trim() : '';
     if (!text) return '';
     const max = Number.isFinite(this.cfg.maxChars) && this.cfg.maxChars > 0 ? this.cfg.maxChars : 200;
-    return text.length > max ? text.slice(0, max) : text;
+    if (text.length <= max) return text;
+    let cut = text.slice(0, max);
+    // 按 UTF-16 硬切会把 emoji 切成孤立代理，URL 编码后变成 %EF%BF%BD（乱码方块）
+    if (/[\uD800-\uDBFF]$/.test(cut)) cut = cut.slice(0, -1);
+    return cut;
   }
 
   private cleanLang(raw: unknown): string {
@@ -285,7 +289,11 @@ export class EllenVoiceWorld implements World {
     }
     const bytes = new Uint8Array(await res.arrayBuffer());
     if (bytes.byteLength < 1024) throw new Error('合成结果为空');
-    const mime = (res.headers.get('content-type') ?? 'audio/wav').split(';')[0].trim();
+    const mime = (res.headers.get('content-type') ?? 'audio/wav').split(';')[0].trim().toLowerCase();
+    // 地址填错时常常是「HTTP 200 + 一张网页」，只比大小会把它当语音存下来
+    if (!mime.startsWith('audio/') && mime !== 'application/octet-stream') {
+      throw new Error(`语音服务返回的不是音频（content-type: ${mime}），检查设置里的 ttsUrl`);
+    }
     const value = { bytes, mime };
     this.memo.set(key, value);
     return value;
@@ -352,6 +360,11 @@ export class EllenVoiceWorld implements World {
       ws.addEventListener('error', () => {
         finish(() => reject(new Error('连不上 OneBot 协议端')));
       });
+      // 协议端可能先把连接下一秒再断开（端口对但 token 错、或连的不是 OneBot）。
+      // 只听 error 的话这种情况不报错，要白等到 MAX_WAIT_MS 才超时，所以这里也接 close。
+      ws.addEventListener('close', () => {
+        finish(() => reject(new Error(`OneBot 连上后立刻断开：检查地址（${this.cfg.oneBotUrl}）和 access_token 是否正确`)));
+      });
     });
   }
 

package/template/figure.js

@@ -0,0 +1,361 @@
+/**
+ * 静态立绘形象包 —— figure.js 最小实现草案（Coopanion pet figure api 2）
+ *
+ * 用途：扩展只生成了 model.json + tex/figure.png（一张整图），没有生成 figure.js，
+ *       于是 figure-frame.js 里 `await import(m.entry)` 失败 → 形象加载失败、回退默认角色。
+ *       这份文件就是补上那个入口模块的最小版本：*只画一张静态图*，不依赖任何第三方库。
+ *
+ * 契约（见 web/figure-frame.js 第 9-42 行注释）：
+ *   - 本模块必须导出 figure.json 里 `export` 字段指名的函数（这里是 createWhaleBody）。
+ *   - 宿主调用：`createWhaleBody(base, { model, scheme, kit, loadImage, asset, host })`
+ *       base: URL           包的根目录 URL（已解析好的绝对地址）
+ *       model: object       model.json 解析后的对象（可能为 undefined，此时自己 fetch）
+ *       scheme: string      初始配色 id（静态包只有一个，可忽略）
+ *       kit:  module        web/kit/body.js 整个命名空间（含 createBody / createPet）
+ *       loadImage(url): Promise<HTMLImageElement>
+ *       asset(path): URL    把包内相对路径解析成绝对 URL
+ *       host: { root, bounds(), emit(kind,detail), sound(name,kind,...args), start }
+ *   - 返回值必须有 step(dt)、layout()、do(word) 三个函数，否则宿主抛 figure.missingMethod。
+ *
+ * 坐标系（kit 的约定，非常重要）：
+ *   一个"logo 单位"方框，256×256；地面线 y = 256；x = 128 是身体中心；角色默认朝右（+x）。
+ *   图里所有元素都用 logo 单位画，宿主的 petG 已经带上了 translate/rotate/scale（1 单位 = S 像素、
+ *   朝左时用负 scale 镜像），所以这里只管在 0..256 的坐标系里画，不用关心像素。
+ */
+
+/* ------------------------------------------------------------------ *
+ * 0. 小工具
+ * ------------------------------------------------------------------ */
+
+const SVGNS = 'http://www.w3.org/2000/svg';
+const XLINKNS = 'http://www.w3.org/1999/xlink';
+
+/** 真机对位微调：立绘在 logo 单位里的额外平移/缩放。默认不动，对不齐时只改这里。 */
+const TWEAK = { dx: 0, dy: 0, scale: 1 };
+
+/** 只有有限数字才用，否则退回默认值（防止 NaN 把整张图画没） */
+const num = (v, d) => (typeof v === 'number' && Number.isFinite(v) ? v : d);
+
+/** 校验一个 [a,b,c,d] 形状的数组 */
+const quad = (v) => (Array.isArray(v) && v.length === 4 && v.every((n) => typeof n === 'number' && Number.isFinite(n)) ? v : null);
+
+/** 宿主没给 loadImage 时的兜底实现（正常情况下 figure-frame.js 一定会给） */
+function defaultLoadImage(url) {
+  return new Promise((ok, bad) => {
+    const im = new Image();
+    im.crossOrigin = 'anonymous';
+    im.onload = () => ok(im);
+    im.onerror = () => bad(new Error('image failed: ' + url));
+    im.src = String(url);
+  });
+}
+
+/** model 可能是对象，也可能是相对/绝对 URL 字符串；都没有就自己去包根目录取 model.json */
+async function resolveModel(base, given) {
+  if (given && typeof given === 'object') return given;
+  try {
+    const url = typeof given === 'string' ? new URL(given, base) : new URL('model.json', base);
+    const res = await fetch(url);
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 从 model.json 里求出「整张立绘应该铺进 logo 单位坐标系里的哪个矩形」。
+ * 优先级：
+ *   1) model.parts 里 id/tex 为 'figure' 的那个 part 的 box=[x,y,w,h]（静态构建脚本写入的，最准）
+ *   2) model.view：模板里是 [-12,-8,268,272]，按 [x,y,w,h] 读（与 part.box 同一种读法；
+ *      rig.js 里把它当 [x0,y0,x1,y1] 用，差 12 个单位，见 report.md「未验证」）
+ *   3) 硬编码模板默认值
+ */
+function artRect(model) {
+  const parts = Array.isArray(model?.parts) ? model.parts : [];
+  const part = parts.find((p) => p && (p.id === 'figure' || p.tex === 'figure'));
+  const box = quad(part?.box);
+  if (box) return { x: box[0], y: box[1], w: box[2], h: box[3] };
+  const view = quad(model?.view);
+  if (view) return { x: view[0], y: view[1], w: view[2], h: view[3] };
+  return { x: -12, y: -8, w: 268, h: 272 };
+}
+
+/* ------------------------------------------------------------------ *
+ * 1. createWhaleFigure：返回 kit 认识的那个 "figure"（只负责画）
+ *
+ * 这是给 opts.kit.createBody(host, { figure }) 用的"画笔"对象。
+ * kit 的可选钩子（web/kit/body.js 第 119-132 行）：
+ *   draw(petG, face, frame)  必填：把元素画进 petG（logo 空间，每帧调用）
+ *   extent                   [x0,y0,x1,y1]：包围盒，宿主拿它算 layout().box（每帧读，也可是 getter）
+ *   hits                     [[x,y,r],...]：点击热区，宿主拿它算 layout().hit
+ *   anchors                  { gaze, tear, z, hearts, bubble }：特效挂点，会覆盖 kit 的默认值
+ *   colors.z                 睡觉 z 的颜色
+ *   setSkin(skin)            换皮肤时通知
+ *   dispose()                卸载
+ * ------------------------------------------------------------------ */
+
+export async function createWhaleFigure(base = new URL('./', import.meta.url), opts = {}) {
+  const model = await resolveModel(base, opts.model);
+  const asset = opts.asset ?? ((p) => new URL(p, base));
+  const load = typeof opts.loadImage === 'function' ? opts.loadImage : defaultLoadImage;
+
+  const rect = artRect(model);
+  const url = String(asset('tex/figure.png'));
+
+  // 先真正加载一次：贴图缺失/路径错时在 ready 之前就抛错，
+  // 宿主会回报 figure.imageFailed 一类的错误，比"画不出东西"好排查得多。
+  const img = await load(url);
+
+  // 静态包只有一个配色；取 model.json 里的 accent 当 z 的颜色
+  const schemes = Array.isArray(model?.schemes) ? model.schemes : [];
+  const accent = typeof schemes[0]?.accent === 'string' ? schemes[0].accent : '#C8102E';
+
+  let hostEl = null; // 当前挂载的 petG
+  let rootG = null; // 平移/呼吸用的外层 <g>
+  let artG = null; // 装 <image> 的 <g>（承载 TWEAK）
+
+  /** 把 <image> 挂进 petG；换宿主或元素被清掉时重建（elen 的实现里同样会 petG.textContent=''） */
+  function mount(petG) {
+    petG.textContent = '';
+    rootG = document.createElementNS(SVGNS, 'g');
+    artG = document.createElementNS(SVGNS, 'g');
+    const im = document.createElementNS(SVGNS, 'image');
+    im.setAttribute('x', String(rect.x));
+    im.setAttribute('y', String(rect.y));
+    im.setAttribute('width', String(rect.w));
+    im.setAttribute('height', String(rect.h));
+    // 贴图是被切成固定画布再拉满这个矩形的，所以直接拉伸（与 rig.js 的行为一致）
+    im.setAttribute('preserveAspectRatio', 'none');
+    im.setAttribute('href', url);
+    im.setAttributeNS(XLINKNS, 'xlink:href', url); // 老一点的内核兜底
+    artG.appendChild(im);
+    rootG.appendChild(artG);
+    petG.appendChild(rootG);
+    hostEl = petG;
+    applyArtTransform();
+  }
+
+  /** TWEAK 需要在 rect 基础上做以脚底为基准的缩放，单独算一个 transform 贴上 */
+  function applyArtTransform() {
+    if (!artG) return;
+    const s = num(TWEAK.scale, 1);
+    const cx = rect.x + rect.w / 2;
+    const by = rect.y + rect.h; // 以图片底边为缩放基准
+    const dx = num(TWEAK.dx, 0);
+    const dy = num(TWEAK.dy, 0);
+    if (s === 1 && dx === 0 && dy === 0) {
+      artG.removeAttribute('transform');
+      return;
+    }
+    artG.setAttribute('transform', `translate(${dx} ${dy}) translate(${cx} ${by}) scale(${s}) translate(${-cx} ${-by})`);
+  }
+
+  /**
+   * 每帧被 kit 调用一次（顺序：先 step 改状态，再 render 调 draw）。
+   * 静态图只做两件小事：行走/奔跑时轻微上下浮，其余保持不动。
+   * 注意：不要在这里重建元素，也不要把 petG 整个清空（会打掉 kit 自己塞进去的东西）。
+   */
+  function draw(petG, _face, frame) {
+    if (hostEl !== petG || !rootG || !rootG.isConnected) mount(petG);
+    const mode = frame?.mode ?? 'idle';
+    const t = num(frame?.t, 0);
+    // 走路时的细小起伏，幅度只有 2 个 logo 单位（≈ 0.8 px @S=0.42），不破坏"静态"观感
+    const bob = mode === 'walk' || mode === 'run' ? Math.sin(t * 9) * 2 : 0;
+    rootG.setAttribute('transform', `translate(0 ${bob.toFixed(2)})`);
+  }
+
+  // 包围盒：就是这张图覆盖的矩形（裁剪过后宿主会拿它当 hover/halo 的框）
+  const extent = [rect.x, rect.y, rect.x + rect.w, rect.y + rect.h];
+
+  // 点击热区：图片中下部一个圆（身体），比默认的 [[128,128,108]] 更贴合
+  const hitCx = rect.x + rect.w / 2;
+  const hitCy = rect.y + rect.h * 0.58;
+  const hits = [[hitCx, hitCy, Math.min(rect.w, rect.h) * 0.36]];
+
+  return {
+    draw,
+
+    /** 睡眠 z / 音符的颜色（kit 用 figure.colors.z） */
+    get colors() {
+      return { z: accent };
+    },
+
+    /** 特效挂点：按矩形比例估算，脸部在偏上位置 */
+    get anchors() {
+      const cx = rect.x + rect.w / 2;
+      return {
+        gaze: [cx, rect.y + rect.h * 0.42],
+        tear: [cx + rect.w * 0.16, rect.y + rect.h * 0.5],
+        z: [rect.x + rect.w * 0.74, rect.y + rect.h * 0.06],
+        hearts: [rect.x + rect.w * 0.3, rect.y + rect.h * 0.55, rect.w * 0.16],
+        bubble: [cx, rect.y + rect.h * 0.04],
+      };
+    },
+
+    get extent() {
+      return extent;
+    },
+
+    get hits() {
+      return hits;
+    },
+
+    /** 静态包只有一张图：任何配色 id 都直接成功返回（宿主 await 它，且会读 body.z） */
+    async setScheme(_id, _o) {
+      return true;
+    },
+
+    /** 换皮肤对静态图没有影响，留空即可 */
+    setSkin(_skin) {},
+
+    dispose() {
+      hostEl = null;
+      rootG = null;
+      artG = null;
+    },
+
+    // 以下两个字段不是契约要求的，但方便调试/他人理解
+    model,
+    art: { url, rect, natural: { w: img.naturalWidth, h: img.naturalHeight } },
+  };
+}
+
+/* 便于直接以 createWhaleBody 的语义复用 */
+export const createWhaleFigureStatic = createWhaleFigure;
+
+/* ------------------------------------------------------------------ *
+ * 2. createWhaleBody：figure.json 的 "export" 指向这里
+ *
+ * 正常路径：拿 kit.createBody 包一层 —— step/layout/do/words/walk/pointer/... 全部由 kit 提供，
+ * 我们只贡献"怎么画一张图"。这样坐、睡、走、摸头、说话口型、地板、拖拽都免费获得。
+ * ------------------------------------------------------------------ */
+
+export async function createWhaleBody(base, opts) {
+  const kit = opts?.kit;
+  if (kit && typeof kit.createBody === 'function' && opts?.host?.root) {
+    const figure = await createWhaleFigure(base, opts);
+    // 只传 figure：不传 words/moves，manifest 的 vocab 由 kit 内置的 38 个词覆盖
+    return kit.createBody(opts.host, { figure });
+  }
+  // 兜底：宿主没给 kit（或 kit 版本对不上）时，自己实现最小三件套
+  return createStaticBody(base, opts);
+}
+
+/* ------------------------------------------------------------------ *
+ * 3. 兜底实现：完全没有 kit 时的最小 step/layout/do
+ *
+ * 只在 opts.kit.createBody 缺失时走到这里。行为刻意做得很笨：
+ * 站着不动、不会走、不会坐，只保证宿主能拿到合法的 layout。
+ * 坐标系换算：stage 像素 = 脚底基准
+ *   屏幕x = 身体x + (logo x - 128) * S
+ *   屏幕y = floorY + (logo y - 256) * S
+ * ------------------------------------------------------------------ */
+
+async function createStaticBody(base, opts) {
+  const host = opts?.host ?? {};
+  const root = host.root;
+  if (!root) throw new Error('static figure: host.root missing');
+
+  const model = await resolveModel(base, opts.model);
+  const asset = opts.asset ?? ((p) => new URL(p, base));
+  const load = typeof opts.loadImage === 'function' ? opts.loadImage : defaultLoadImage;
+  const rect = artRect(model);
+  const url = String(asset('tex/figure.png'));
+  await load(url);
+
+  const doc = root.ownerDocument;
+  const svg = doc.createElementNS(SVGNS, 'svg');
+  svg.setAttribute('aria-hidden', 'true');
+  svg.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;pointer-events:none';
+  const g = doc.createElementNS(SVGNS, 'g');
+  const im = doc.createElementNS(SVGNS, 'image');
+  im.setAttribute('x', String(rect.x));
+  im.setAttribute('y', String(rect.y));
+  im.setAttribute('width', String(rect.w));
+  im.setAttribute('height', String(rect.h));
+  im.setAttribute('preserveAspectRatio', 'none');
+  im.setAttribute('href', url);
+  im.setAttributeNS(XLINKNS, 'xlink:href', url);
+  g.appendChild(im);
+  svg.appendChild(g);
+  root.appendChild(svg);
+
+  const bounds = () => (typeof host.bounds === 'function' ? host.bounds() : { W: 0, H: 0, floorY: 0, S: 0.42 });
+  const start = host.start ?? {};
+  const st = {
+    x: num(start.x, bounds().W / 2), // 身体中心的 stage x
+    facing: start.facing === -1 ? -1 : 1,
+    mode: 'idle',
+    t: 0,
+  };
+
+  const toStageX = (lx) => st.x + (lx - 128) * bounds().S;
+  const toStageY = (ly) => bounds().floorY + (ly - 256) * bounds().S;
+
+  function paint() {
+    const b = bounds();
+    const S = num(b.S, 0.42);
+    const bob = 0;
+    g.setAttribute('transform', `translate(${st.x.toFixed(2)} ${(b.floorY + bob).toFixed(2)}) scale(${(S * st.facing).toFixed(5)} ${S.toFixed(5)}) translate(-128 -256)`);
+    svg.setAttribute('width', String(b.W));
+    svg.setAttribute('height', String(b.H));
+    svg.setAttribute('viewBox', `0 0 ${b.W} ${b.H}`);
+  }
+
+  function layout() {
+    const S = num(bounds().S, 0.42);
+    const x0 = toStageX(rect.x);
+    const y0 = toStageY(rect.y);
+    const box = { x: x0, y: y0, w: rect.w * S, h: rect.h * S };
+    return {
+      x: st.x,
+      facing: st.facing,
+      mode: st.mode,
+      busy: false,
+      moving: false,
+      pressing: false,
+      cursor: '',
+      box,
+      hit: [{ x: toStageX(rect.x + rect.w / 2), y: toStageY(rect.y + rect.h * 0.58), r: Math.min(rect.w, rect.h) * 0.36 * S }],
+      bubble: { x: toStageX(rect.x + rect.w / 2), y: y0 },
+      side: { x: st.x, y: toStageY(256), reach: 104 * S },
+    };
+  }
+
+  paint();
+  return {
+    step(dt) {
+      st.t += num(dt, 0);
+      paint();
+    },
+    layout,
+    /**
+     * 只认识 turn；其余单词安静地返回 true，避免宿主以为它"忙"。
+     * 这里刻意**不**返回 words：宿主没收到 words 时按 manifest 的 vocab 全信，
+     * 如果只声明 ['turn']，World 会警告"词表里有身体不认得的词"。
+     */
+    do(word) {
+      if (word === 'turn') st.facing = -st.facing;
+      return true;
+    },
+    resize() {
+      paint();
+    },
+    async setScheme() {
+      return true;
+    },
+    get z() {
+      const schemes = Array.isArray(model?.schemes) ? model.schemes : [];
+      return typeof schemes[0]?.accent === 'string' ? schemes[0].accent : null;
+    },
+    dispose() {
+      svg.remove();
+    },
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * 4. 默认导出：有些加载器会尝试 mod.default，顺手给它一个同样的工厂
+ * ------------------------------------------------------------------ */
+
+export default createWhaleBody;