@ganziliang/desktop-pet 0.1.0

package/renderer/app.js

@@ -0,0 +1,1219 @@
+'use strict';
+
+/**
+ * 桌面小控件 —— 渲染层
+ *
+ * 交互总览
+ *   拖拽        按住角色拖动窗口，摆动幅度随速度变化，松手有落地弹性
+ *   单击        跳一下 + 甜妹语气台词 + 飘爱心
+ *   双击        跳舞
+ *   鼠标悬停     眼睛/身体跟随光标轻微偏移，高亮
+ *   长时间不动    打瞌睡，鼠标一靠近就醒
+ *   右键        原生菜单（动作 / 穿透 / 置顶 / 缩放 / 退出）
+ *   透明区域     自动鼠标穿透，不挡桌面其它图标
+ *
+ * 外部消息：主进程 HTTP 接口 -> pet:say -> 气泡 + 说话动画
+ */
+
+const LINES = [
+  '呜哇，你终于点我啦～',
+  '在的在的，我一直都在这里陪着你哦！',
+  '今天的代码也要好好写哦，我超相信你的～',
+  '诶嘿，被你抓到啦！',
+  '要不要休息一下呀？眼睛也是要爱护的嘛～',
+  '我我我……我会加油的！',
+  '你看起来有点累呢，喝口水好不好？',
+  '唔……刚刚是不是有个 bug 想跑掉？',
+  '摸头的话，我可是会害羞的哦～',
+  '今天也超级棒！记得夸夸自己呀！',
+  '偷偷告诉你，我最喜欢认真工作的你了～',
+  '需要抱抱吗？免费的哦，仅限今天！',
+];
+
+const IDLE_MS = 75_000; // 无操作多久后睡觉
+const HIT_ALPHA = 26; // 命中测试的 alpha 阈值
+const CLICK_SLOP = 12; // 松手时总位移小于此值按单击处理（手抖容差）
+const ROAM_GAP_MS = [6000, 15000]; // 两次自动活动之间的间隔区间
+const WATER_H = 152; // 水面高度（CSS px），要与 style.css 的 .water height 一致
+const SWIM_SUBMERGE = 0.42; // 游泳时水线切在身体自下往上多少比例处
+// 每种动作「每帧停留多久」，一轮帧循环的时长 = 帧数 × 这个值（所以帧数改了不用改这里）
+const PER_FRAME_MS = { walk: 150, run: 75, swim: 200 };
+/**
+ * 自主活动的动作权重 —— 写多少 = 一轮发牌里出现几张。
+ *
+ * 觉醒用 'awaken:*' 通配，写多少 = 「每套觉醒各几张」。
+ * 这里 walk/run/swim 各 4 张、每套觉醒各 5 张，一沓 32 张：
+ *   单个觉醒 5/32 = 15.6%，单个平时动作 4/32 = 12.5%
+ * 也就是「觉醒比平时动作略容易抽到一点点」（1.25 倍）。
+ * 想让觉醒稀有回去，把 5 改成 1 就行（1/16 ≈ 6%）；想让它更常出就继续加大。
+ */
+const ROAM_WEIGHTS = { walk: 4, run: 4, swim: 4, 'awaken:*': 5 };
+/**
+ * 觉醒演出之后歇多久再考虑下一次活动。
+ * 觉醒占屏 5.7 秒、还是放大窗口的演出，刚完就又接一次会很像卡住；
+ * 而且发牌只决定「这一张是什么」，没有这个停顿的话连着抽到两张觉醒
+ * 会真的背靠背放两次。
+ */
+const AWAKEN_REST_MS = [24000, 52000];
+/**
+ * 调参 / 自动化用：PET_ROAM_GAP_MS=<毫秒>（主进程从环境变量读，随 getConfig 发下来）。
+ * 设了就同时接管「两次活动的间隔」和「觉醒后的停顿」两个随机区间 —— 不开就是正常节奏。
+ */
+let gapOverride = null;
+
+function nextGap(range) {
+  if (gapOverride) return gapOverride;
+  return range[0] + Math.random() * (range[1] - range[0]);
+}
+
+const el = {};
+const state = {
+  anim: 'idle',
+  dragging: false,
+  pressed: false,
+  movedFar: false,
+  sleeping: false,
+  hover: false,
+  dragDist: 0,
+  scale: 1,
+  interactive: null,
+  talkUntil: 0,
+  roaming: false,
+  roamMode: null,
+  awakening: false, // 觉醒演出中：巡游/小动作/睡觉全部让位
+  autoAwaken: false, // 这次觉醒是自主发牌抽到的（手动触发的不该跟着歇那么久）
+  face: 1, // 1 = 朝右，-1 = 朝左
+  sheetKey: null,
+  sheetW: 0,
+  sheetH: 0,
+  sheetPadY: 0,
+  sheetFrames: 1,
+};
+
+let cfg = { assets: {} };
+let hitCtx = null;
+let hitCanvas = null;
+const sheetCache = new Map();
+
+let idleTimer = null;
+let blinkTimer = null;
+let microTimer = null;
+let bubbleTimer = null;
+let typingTimer = null;
+let roamTimer = null;
+let gaitTimer = null;
+let greetTimer = null;
+let lastPointer = { x: 0, y: 0, sx: 0, sy: 0 };
+let lastHitCheck = 0;
+let lineBag = [];
+let dragOrigin = null;
+let moveTicks = 0;
+let dbgOn = false;
+
+function dbg(...parts) {
+  if (dbgOn) window.pet.debug(parts.join(' '));
+}
+
+// 渲染层的异常不会自己跳到终端，统一转给主进程的 pet-debug.log，
+// 不然出错时只能看到一个「特效没出来」的现象。
+window.addEventListener('error', (e) => {
+  window.pet?.debug?.(`ERROR ${e.message} @${e.filename}:${e.lineno}:${e.colno}`);
+});
+window.addEventListener('unhandledrejection', (e) => {
+  window.pet?.debug?.(`REJECT ${e.reason?.stack || e.reason}`);
+});
+
+/* -------------------------------------------------------------- 小工具 */
+
+function toFileUrl(p) {
+  if (!p) return '';
+  return `file:///${String(p).replace(/\\/g, '/').replace(/^\//, '')}`;
+}
+
+function pickLine() {
+  if (lineBag.length === 0) lineBag = LINES.slice().sort(() => Math.random() - 0.5);
+  return lineBag.pop();
+}
+
+window.__petRandomLine = pickLine;
+
+function setAnim(name, restoreAfter = 0) {
+  // 巡游中不允许被 "idle" 顶掉（说话/微动作的定时器可能刚好在这个当口回来）
+  if (name === 'idle' && state.roaming) return;
+  state.anim = name;
+  el.stage.dataset.anim = name;
+  if (restoreAfter > 0) {
+    const token = name + ':' + Date.now();
+    el.stage.dataset.animToken = token;
+    setTimeout(() => {
+      if (el.stage.dataset.animToken === token && state.anim === name) setAnim('idle');
+    }, restoreAfter);
+  }
+}
+
+/* ------------------------------------------------------------ 精灵图 */
+
+function placeholderSheet() {
+  return {
+    url: placeholderCharacter(),
+    frames: 1,
+    figH: 360,
+    natW: 240,
+    natH: 360,
+    img: null,
+  };
+}
+
+let placeholderUrl = '';
+const sheetStore = new Map(); // key -> 已加载的 sheet 对象
+
+function placeholderSheet() {
+  if (!placeholderUrl) placeholderUrl = placeholderCharacter();
+  return {
+    url: placeholderUrl,
+    frames: 1,
+    refPx: 360,
+    frameW: 240,
+    frameH: 360,
+    axis: 'h',
+    padY: 0,
+    img: null,
+  };
+}
+
+/** 加载一张精灵图（同一路径只加载一次） */
+function loadSheet(conf) {
+  if (!conf?.path) return Promise.resolve(null);
+  if (sheetCache.has(conf.path)) return sheetCache.get(conf.path);
+  const p = new Promise((resolve) => {
+    const im = new Image();
+    im.onload = () => resolve({ ...conf, url: toFileUrl(conf.path), img: im });
+    im.onerror = () => resolve(null);
+    im.src = toFileUrl(conf.path);
+  });
+  sheetCache.set(conf.path, p);
+  return p;
+}
+
+function confFor(key) {
+  if (key === 'idle') return cfg.assets?.idle || null;
+  if (key === 'blink') return cfg.assets?.blink || null;
+  return cfg.assets?.sheets?.[key] || null;
+}
+
+/**
+ * 开场先把所有图加载完。这样切动作就只是换 CSS 背景，是同步的，
+ * 不会出现「已经迈步了但还挂着站立图」那一两帧。
+ */
+async function preloadSheets() {
+  const keys = ['idle', 'walk', 'run', 'swim', 'blink'];
+  await Promise.all(
+    keys.map(async (k) => {
+      const conf = confFor(k);
+      if (!conf) return;
+      const s = await loadSheet(conf);
+      if (s) sheetStore.set(k, s);
+    }),
+  );
+  if (!sheetStore.has('idle')) sheetStore.set('idle', placeholderSheet());
+
+  // 觉醒序列帧（蓄力 / 爆发 / 旧版单帧立绘）也走同一套 sheet 机制。
+  // 关键：它们和 idle 用同一个 refPx 归一化公式，所以换装那一瞬间不会忽大忽小。
+  // 缺哪个阶段就不放进 store，演出自己退回 idle 帧 —— 光效照跑。
+  for (const [id, phases] of Object.entries(cfg.assets?.awaken || {})) {
+    for (const [phase, conf] of Object.entries(phases)) {
+      const s = await loadSheet({ ...conf, axis: 'h', padY: conf.padY || 0 });
+      if (s) sheetStore.set(`awaken:${id}:${phase}`, s);
+    }
+  }
+
+  const missing = ['walk', 'run', 'swim'].filter((k) => !sheetStore.has(k));
+  if (missing.length) dbg(`缺少动作精灵图：${missing.join(',')} —— 这几个动作会退回 idle 帧`);
+}
+
+/**
+ * 切到某张精灵图：换背景图 + 按「角色标准屏幕身高」反推帧的显示尺寸。
+ * 所有动作图里角色都被归一化到同一身高，所以来回切不会忽大忽小、跳位置。
+ */
+function useSheet(key) {
+  const sheet = sheetStore.get(key) || sheetStore.get('idle');
+  if (!sheet) return false;
+
+  // 觉醒演出会直接写 backgroundPositionX 来逐帧播放（不走 steps() 动画），
+  // 所以换表时必须清掉上一次留下的偏移，否则新表一上来就偏几帧。
+  el.sprite.style.backgroundPositionX = '0px';
+
+  // refPx 是「角色在这张图里有多大」：竖构图是身高，游泳那种横躺图是身长。
+  // 都换算到同一个屏幕尺寸，所以站立↔跑步↔游泳来回切不会忽大忽小。
+  const figDisp = (cfg.assets?.figureHeight ?? 378) * state.scale;
+  const k = figDisp / sheet.refPx;
+  const fw = Math.max(1, Math.round(sheet.frameW * k));
+  const fh = Math.max(1, Math.round(sheet.frameH * k));
+
+  const changed = state.sheetKey !== key || state.sheetW !== fw || state.sheetH !== fh;
+  state.sheetKey = key;
+  state.sheetW = fw;
+  state.sheetH = fh;
+  state.sheetPadY = (sheet.padY || 0) * k;
+  state.sheetFrames = sheet.frames;
+  el.sprite.style.width = `${fw}px`;
+  el.sprite.style.height = `${fh}px`;
+  el.sprite.style.backgroundImage = `url("${sheet.url}")`;
+  el.sprite.style.backgroundSize = `${fw * sheet.frames}px ${fh}px`;
+  el.character.style.height = `${fh}px`;
+  el.stage.style.setProperty('--nframes', String(sheet.frames));
+  el.stage.style.setProperty('--fw', `${fw}px`);
+  el.stage.style.setProperty('--strip', `${fw * sheet.frames}px`);
+  el.stage.style.setProperty('--fh', `${fh}px`);
+
+  // 命中测试始终用 idle 帧：姿势一直在变，用基准姿势当命中区才不会时灵时不灵
+  if (key === 'idle' && sheet.img && changed) buildHitMask(sheet.img);
+  if (changed) {
+    dbg(
+      `sheet=${key} ${sheet.frames}帧 帧${sheet.frameW}x${sheet.frameH} ref=${sheet.refPx}(${sheet.axis}) -> ${fw}x${fh}`,
+    );
+  }
+  return true;
+}
+
+/**
+ * 游泳时角色是横躺的，不能按「脚踩地面」定位，得让身体骑在水线上。
+ * 帧图上下各留了 padY 的内边距，所以真正的身体底边 = 窗口底 + padY - sink。
+ * 解一下：让水线落在身体自下往上的 SWIM_SUBMERGE 处。
+ */
+function swimSink() {
+  const padY = state.sheetPadY || 0;
+  const bodyH = Math.max(1, state.sheetH - 2 * padY);
+  return Math.round(6 + padY - WATER_H * state.scale + SWIM_SUBMERGE * bodyH);
+}
+
+/** 一轮帧循环的时长：帧数 × 每帧停留时长 */
+function gaitFor(mode) {
+  return Math.round((state.sheetFrames || 4) * (PER_FRAME_MS[mode] || 150));
+}
+
+function setMoving(on) {
+  el.sprite.classList.toggle('moving', !!on);
+}
+
+/* ------------------------------------------------------ 命中测试（alpha） */
+
+function buildHitMask(img) {
+  try {
+    hitCanvas = document.createElement('canvas');
+    hitCanvas.width = img.naturalWidth;
+    hitCanvas.height = img.naturalHeight;
+    hitCtx = hitCanvas.getContext('2d', { willReadFrequently: true });
+    hitCtx.drawImage(img, 0, 0);
+  } catch {
+    hitCtx = null; // 拿不到像素就退化成矩形命中
+  }
+}
+
+function hitTest(x, y) {
+  const r = el.sprite.getBoundingClientRect();
+  if (x < r.left || x > r.right || y < r.top || y > r.bottom) return false;
+  if (!hitCtx) return true;
+
+  const nx = Math.floor(((x - r.left) / r.width) * hitCanvas.width);
+  const ny = Math.floor(((y - r.top) / r.height) * hitCanvas.height);
+  if (nx < 0 || ny < 0 || nx >= hitCanvas.width || ny >= hitCanvas.height) return false;
+
+  try {
+    return hitCtx.getImageData(nx, ny, 1, 1).data[3] > HIT_ALPHA;
+  } catch {
+    return true;
+  }
+}
+
+function setInteractive(next) {
+  if (state.interactive === next) return;
+  state.interactive = next;
+  window.pet.setInteractive(next);
+}
+
+/** 命中测试的详细快照，只在调试模式用 */
+function hitDebug(x, y) {
+  const r = el.sprite.getBoundingClientRect();
+  const inside = x >= r.left && x <= r.right && y >= r.top && y <= r.bottom;
+  let alpha = -1;
+  if (inside && hitCtx) {
+    const nx = Math.floor(((x - r.left) / r.width) * hitCanvas.width);
+    const ny = Math.floor(((y - r.top) / r.height) * hitCanvas.height);
+    try {
+      alpha = hitCtx.getImageData(nx, ny, 1, 1).data[3];
+    } catch {
+      alpha = -2;
+    }
+  }
+  return (
+    `at=${Math.round(x)},${Math.round(y)} inside=${inside} alpha=${alpha} ` +
+    `rect=${Math.round(r.left)},${Math.round(r.top)},${Math.round(r.width)}x${Math.round(r.height)} ` +
+    `canvas=${hitCanvas ? `${hitCanvas.width}x${hitCanvas.height}` : 'none'} ` +
+    `sheet=${state.sheetKey} ${state.sheetW}x${state.sheetH}`
+  );
+}
+
+/* ---------------------------------------------------------------- 气泡 */
+
+function say(text, { mood } = {}) {
+  // 觉醒演出只有几秒，但很怕被打断：这会儿推消息进来会直接把动作顶成 talk
+  if (state.awakening) return;
+  const content = String(text ?? '').slice(0, 500);
+  if (!content) return;
+  wake();
+
+  clearTimeout(bubbleTimer);
+  clearInterval(typingTimer);
+
+  el.bubble.classList.add('show');
+  el.bubbleText.textContent = '';
+  el.text.scrollTop = 0;
+
+  if (mood === 'sleep' || mood === 'zzz') {
+    setAnim('sleep');
+  }
+
+  // 逐字显示
+  let i = 0;
+  typingTimer = setInterval(() => {
+    el.bubbleText.textContent = content.slice(0, ++i);
+    if (i >= content.length) clearInterval(typingTimer);
+  }, 34);
+
+  // 说话动画（张嘴效果：快速在睁眼/闭眼帧间切换）
+  const talkMs = Math.min(9000, 1400 + content.length * 95);
+  state.talkUntil = Date.now() + talkMs;
+  if (!state.sleeping) setAnim('talk');
+  setTimeout(() => {
+    if (Date.now() >= state.talkUntil && !state.sleeping && !state.roaming) setAnim('idle');
+  }, talkMs);
+
+  bubbleTimer = setTimeout(() => el.bubble.classList.remove('show'), talkMs + 1200);
+}
+
+/* ---------------------------------------------------------------- 粒子 */
+
+const PARTICLE_KINDS = {
+  heart: { cls: 'heart', chars: ['💗', '💖', '✨', '💕'], count: 5, life: 1900 },
+  dust: { cls: 'dust', chars: ['·', '｡', '•'], count: 2, life: 800 },
+  bubble: { cls: 'bubble-p', chars: ['○', '◦', '·'], count: 2, life: 1500 },
+  splash: { cls: 'splash', chars: ['💧', '✨', '｡'], count: 6, life: 1000 },
+  ripple: { cls: 'ripple', chars: [''], count: 1, life: 1300 },
+};
+
+/**
+ * 粒子统一下发：爱心在身体中上部，尘土/水花在脚下，涟漪在水面高度。
+ * 坐标用 anchor 的视口矩形算，和窗口同坐标系。
+ */
+function spawnParticles(kind, count) {
+  const spec = PARTICLE_KINDS[kind];
+  if (!spec) return;
+  const rect = el.anchor.getBoundingClientRect();
+  const n = count ?? spec.count;
+  for (let i = 0; i < n; i++) {
+    const p = document.createElement('div');
+    p.className = `p ${spec.cls}`;
+    const up =
+      kind === 'heart'
+        ? 0.15 + Math.random() * 0.4
+        : kind === 'ripple'
+          ? 0.86
+          : 0.72 + Math.random() * 0.2;
+    p.style.left = `${rect.left + rect.width * (0.18 + Math.random() * 0.64)}px`;
+    p.style.top = `${rect.top + rect.height * up}px`;
+    // 尘土/水花往身后飘（--drift 带朝向），气泡往反方向浮
+    const back = -state.face * (24 + Math.random() * 40);
+    const drift = kind === 'bubble' ? -back * 0.4 : kind === 'heart' ? (Math.random() - 0.5) * 60 : back;
+    p.style.setProperty('--drift', `${drift}px`);
+    p.style.setProperty('--rise', `${-(24 + Math.random() * 40)}px`);
+    p.style.animationDelay = `${i * 60}ms`;
+    p.textContent = spec.chars[Math.floor(Math.random() * spec.chars.length)];
+    el.hearts.appendChild(p);
+    setTimeout(() => p.remove(), spec.life + i * 60);
+  }
+}
+
+function spawnHearts(count = 5) {
+  spawnParticles('heart', count);
+}
+
+/* ------------------------------------------------------------ 闲置逻辑 */
+
+function awake() {
+  return !state.sleeping;
+}
+
+function wake() {
+  const wasSleeping = state.sleeping;
+  state.sleeping = false;
+  el.stage.classList.remove('sleeping');
+  if (wasSleeping) {
+    setAnim('idle');
+    say('唔……我醒了我醒了！你回来啦～');
+  }
+  resetIdleTimer();
+}
+
+function resetIdleTimer() {
+  clearTimeout(idleTimer);
+  idleTimer = setTimeout(() => {
+    if (state.awakening) return resetIdleTimer();
+    // 睡着前先把巡游停下，不然会边睡边走
+    if (state.roaming) {
+      window.pet.haltRoam();
+      endLoco('sleep');
+    }
+    state.sleeping = true;
+    el.stage.classList.add('sleeping');
+    setAnim('sleep');
+    el.bubble.classList.remove('show');
+    el.bubbleText.textContent = 'Zzz…';
+    el.bubble.classList.add('show');
+    setTimeout(() => {
+      if (state.sleeping) el.bubble.classList.remove('show');
+    }, 4000);
+  }, IDLE_MS);
+}
+
+/* --------------------------------------------------------------- 眨眼 */
+
+function scheduleBlink() {
+  clearTimeout(blinkTimer);
+  const wait = state.sleeping ? 5200 : 2600 + Math.random() * 3200;
+  blinkTimer = setTimeout(() => {
+    // 只有站着眨眼：跑动/游泳的帧图本来就有自己的表情，而且帧几何不一样
+    const blink = sheetStore.get('blink');
+    if (!state.dragging && state.sheetKey === 'idle') {
+      if (blink) {
+        el.sprite.style.backgroundImage = `url("${blink.url}")`;
+        setTimeout(() => {
+          const idle = sheetStore.get('idle');
+          if (state.sheetKey === 'idle' && idle) {
+            el.sprite.style.backgroundImage = `url("${idle.url}")`;
+          }
+        }, 130);
+      } else {
+        el.stage.classList.add('blinking');
+        setTimeout(() => el.stage.classList.remove('blinking'), 130);
+      }
+    }
+    scheduleBlink();
+  }, wait);
+}
+
+/* --------------------------------------------------------- 随机小动作 */
+
+function scheduleMicro() {
+  clearTimeout(microTimer);
+  microTimer = setTimeout(
+    () => {
+      if (awake() && !state.dragging && !state.pressed && !state.roaming && !state.awakening && Math.random() < 0.55) {
+        if (Math.random() < 0.25) {
+          setAnim('dance', 2800);
+        } else if (Math.random() < 0.35) {
+          setAnim('shake', 500);
+        } else {
+          // 左右张望
+          el.sprite.style.setProperty('--look-x', `${(Math.random() - 0.5) * 14}px`);
+          setTimeout(() => el.sprite.style.setProperty('--look-x', '0px'), 900);
+        }
+      }
+      scheduleMicro();
+    },
+    9000 + Math.random() * 9000,
+  );
+}
+
+/* ------------------------------------------------- 自动活动（走 / 跑 / 游） */
+
+function busy() {
+  return state.dragging || state.roaming;
+}
+
+/**
+ * 能不能现在开始一段自主演出（走路/跑步/游泳，或者觉醒）。
+ * force = 用户明确要求（菜单 / HTTP 点名，可以在说话/跳舞时插队）。
+ * 名字还叫 canRoam，但它现在是「自主行为总闸」—— 觉醒走的是同一套条件。
+ */
+function canRoam(force) {
+  if (!window.pet.roam) return false;
+  if (state.dragging || state.pressed || state.roaming) return false;
+  if (state.awakening) return false;
+  if (!awake()) return false;
+  if (!force && state.anim !== 'idle') return false;
+  return true;
+}
+
+// 动作袋：不是每次独立抛骰子，而是把一轮的动作洗完牌再一张张发。
+// 纯随机会出现「连走三次都不游」，而用户又看不出来那是随机；发牌则是「每 N 次里必定各来一次」，
+// 顺序仍然随机，不会显得机械。
+let roamBag = [];
+
+function buildRoamBag() {
+  const bag = [];
+  const awakenIds = window.AWAKENS?.order || [];
+  for (const [key, n] of Object.entries(ROAM_WEIGHTS)) {
+    if (key === 'awaken:*') {
+      // 每套觉醒各发 n 张，抽到哪张就是哪套
+      for (const id of awakenIds) {
+        for (let i = 0; i < n; i++) bag.push(`awaken:${id}`);
+      }
+    } else {
+      for (let i = 0; i < n; i++) bag.push(key);
+    }
+  }
+  // Fisher-Yates
+  for (let i = bag.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [bag[i], bag[j]] = [bag[j], bag[i]];
+  }
+  // 一沓 32 张，不逐张打日志（太长了），只报构成
+  const tally = {};
+  for (const c of bag) {
+    const k = c.startsWith('awaken:') ? 'awaken' : c;
+    tally[k] = (tally[k] || 0) + 1;
+  }
+  dbg(`roam-bag 新一轮发牌 ${bag.length} 张：${JSON.stringify(tally)}`);
+  return bag;
+}
+
+function pickRoamMode() {
+  if (roamBag.length === 0) roamBag = buildRoamBag();
+  return roamBag.shift(); // 从头部取，日志里的发牌顺序就是实际执行顺序
+}
+
+async function doRoam(mode, { force = false } = {}) {
+  if (!canRoam(force)) return false;
+  let plan = null;
+  try {
+    plan = await window.pet.roam(mode); // 主进程已经开动了，顺便把轨迹计划回传
+  } catch {
+    plan = null;
+  }
+  if (!plan) return false;
+  beginLoco(plan);
+  return true;
+}
+
+/**
+ * 发牌：出什么就执行什么。牌可能是 'walk'/'run'/'swim'，也可能是 'awaken:seraph'。
+ * 觉醒这张牌自己会管下次什么时候再抽（见 releaseShow 里的 AWAKEN_REST_MS），
+ * 所以这里直接 return，不再 scheduleRoam —— 否则会和演出结束时的排程撞车。
+ */
+function playCard(card) {
+  if (card.startsWith('awaken:')) {
+    const id = card.slice('awaken:'.length);
+    playAwaken(id, { auto: true })
+      .then((ok) => {
+        if (!ok) scheduleRoam(); // 没起来（正在说话/拖拽/已经在演出）就正常续轮
+      })
+      .catch(() => scheduleRoam());
+    return;
+  }
+  doRoam(card).catch(() => {});
+  scheduleRoam();
+}
+
+/** 自主行为的节拍器：过 6~15 秒看一眼，现在适不适合动一动 */
+function scheduleRoam(delay) {
+  clearTimeout(roamTimer);
+  const wait = delay ?? nextGap(ROAM_GAP_MS);
+  roamTimer = setTimeout(() => {
+    if (cfg.autoRoam === false) return scheduleRoam(8000);
+    if (!canRoam()) return scheduleRoam(2600); // 在睡觉 / 在说话 / 拖拽中，缓一下再看
+    playCard(pickRoamMode());
+  }, wait);
+}
+
+/** 按主进程给的 plan 进入对应的运动状态 */
+function beginLoco(plan) {
+  state.roaming = true;
+  state.roamMode = plan.mode;
+  state.face = plan.dir < 0 ? -1 : 1;
+  el.facer.style.setProperty('--face', String(state.face));
+  el.stage.classList.toggle('swimming', plan.mode === 'swim');
+  useSheet(plan.mode); // 先换图，gait 要用到新图的帧数
+  setMoving(true);
+  // 步频跟着帧数走，不是写死的常数
+  el.stage.style.setProperty('--gait', `${gaitFor(plan.mode)}ms`);
+
+  if (plan.mode === 'swim') {
+    el.anchor.style.setProperty('--sink', `${swimSink()}px`);
+    spawnParticles('splash', 7);
+  } else {
+    el.anchor.style.setProperty('--sink', '0px');
+    if (plan.mode === 'run') spawnParticles('dust', 3);
+  }
+  setAnim(plan.mode);
+  startGaitFx(plan.mode);
+  dbg(`loco-start mode=${plan.mode} dir=${plan.dir} dist=${plan.dist} dur=${plan.duration}`);
+}
+
+function endLoco(reason = 'arrived') {
+  if (!state.roaming) return;
+  const mode = state.roamMode;
+  state.roaming = false;
+  state.roamMode = null;
+  stopGaitFx();
+  setMoving(false);
+  useSheet('idle'); // 帧动画停了，回到站立帧
+  if (mode === 'swim') spawnParticles('splash', 5);
+  el.anchor.style.setProperty('--sink', '0px');
+  el.stage.classList.remove('swimming');
+  if (reason === 'drag') setAnim('idle');
+  else setAnim('land', 480);
+  dbg(`loco-end mode=${mode} reason=${reason}`);
+}
+
+/** 跑动时周期性踢起尘土 / 冒泡 / 泛涟漪 */
+function startGaitFx(mode) {
+  stopGaitFx();
+  const gap = mode === 'run' ? 170 : mode === 'swim' ? 430 : 640;
+  gaitTimer = setInterval(() => {
+    if (!state.roaming) return stopGaitFx();
+    if (mode === 'run') {
+      spawnParticles('dust', 2);
+    } else if (mode === 'swim') {
+      spawnParticles('bubble', 2);
+      if (Math.random() < 0.6) spawnParticles('ripple', 1);
+    } else if (Math.random() < 0.5) {
+      spawnParticles('dust', 1);
+    }
+  }, gap);
+}
+
+function stopGaitFx() {
+  clearInterval(gaitTimer);
+  gaitTimer = null;
+}
+
+/** 截图自检 / 视觉回归：不走位，只把某个动作状态摆好 */
+function applyDemo(anim) {
+  clearTimeout(roamTimer);
+  clearTimeout(greetTimer); // 不然开机那句台词会把 demo 动作顶成 talk
+  el.bubble.classList.remove('show');
+  state.roaming = true; // 锁住，否则 setAnim('idle') 会把 demo 动画顶掉
+  state.roamMode = anim;
+  state.face = 1;
+  el.facer.style.setProperty('--face', '1');
+  useSheet(anim);
+  setMoving(true);
+  el.stage.style.setProperty('--gait', `${gaitFor(anim)}ms`);
+  if (anim === 'swim') {
+    el.stage.classList.add('swimming');
+    el.anchor.style.setProperty('--sink', `${swimSink()}px`);
+    spawnParticles('splash', 6);
+  } else if (anim === 'run') {
+    spawnParticles('dust', 4);
+  }
+  setAnim(anim);
+  startGaitFx(anim);
+  dbg(`demo anim=${anim}`);
+}
+
+/* ---------------------------------------------------------- 觉醒技能 */
+
+/**
+ * 一场觉醒演出的时间线（毫秒）：
+ *   0            黑屏切入（canvas 暗幕）
+ *   180          窗口放大 + 换上战斗服立绘 + 「镜头推近」
+ *   revealAt     暗幕退 + 白闪 + 画面抖动 + 主爆发（具体特效由各套觉醒的 build 排）
+ *   closeAt      暗幕再进 + 窗口收回（正好盖住窗口变回去的那一帧）
+ *   duration     暗幕退掉，回到站立
+ *
+ * 关键点：窗口尺寸是在「暗幕已经盖满」之后才改的，所以看不到窗口在变形。
+ * DNF 的觉醒也是这么处理的 —— 黑屏切入从来不只是省钱，它负责把不好看的那一帧藏起来。
+ */
+
+let awakenToken = 0; // 每次演出一个令牌；旧演出的挂起回调拿它对不上号就自己失效
+
+/** 角色当前的屏幕位置，事件在触发的那一刻现取（窗口刚被放大过） */
+/**
+ * 觉醒演出的逐帧播放：直接写 backgroundPositionX，不走 steps() 帧动画。
+ * 为什么不用 CSS 帧动画：一套觉醒要「蓄力慢、爆发快」两种节奏，
+ * steps() 一条动画只能一个速度；而且帧要和特效时间轴对死，写死帧号最直接。
+ */
+function awakenFrame(idx) {
+  setMoving(false);
+  el.sprite.style.backgroundPositionX = `${-idx * (state.sheetW || 0)}px`;
+}
+
+function awakenPoint() {
+  const r = el.sprite.getBoundingClientRect();
+  const cx = r.left + r.width / 2;
+  return {
+    w: window.innerWidth,
+    h: window.innerHeight,
+    cx,
+    cy: r.top + r.height / 2,
+    footX: cx,
+    footY: r.bottom,
+  };
+}
+
+function holdShow() {
+  state.awakening = true;
+  state.sleeping = false;
+  el.stage.classList.remove('sleeping');
+  el.bubble.classList.remove('show');
+  el.bubbleText.textContent = '';
+  clearTimeout(roamTimer);
+  clearTimeout(microTimer);
+  clearTimeout(idleTimer);
+  clearTimeout(blinkTimer);
+  clearTimeout(greetTimer);
+  stopGaitFx();
+  setInteractive(false); // 演出期间别挡着桌面，鼠标直接穿过去
+}
+
+function releaseShow() {
+  const wasAuto = state.autoAwaken;
+  state.awakening = false;
+  state.autoAwaken = false;
+  el.stage.classList.remove('awakening', 'flashing', 'shaking');
+  el.stage.style.removeProperty('--awaken-zoom');
+  useSheet('idle');
+  setAnim('idle');
+  resetIdleTimer();
+  scheduleBlink();
+  scheduleMicro();
+  // 自己抽到的觉醒歇久一点：它的牌权重本来就比平时动作高，不缓和一下
+  // 就会变成「一分钟一次大演出」，很挡事。用户手动点的就正常续轮即可。
+  scheduleRoam(nextGap(wasAuto ? AWAKEN_REST_MS : ROAM_GAP_MS));
+}
+
+/** 爆发那一刻：白闪 + 抖屏 */
+function awakenReveal(token) {
+  if (token !== awakenToken) return;
+  el.stage.classList.remove('flashing', 'shaking');
+  void el.stage.offsetWidth; // 强制重排，否则同一个 class 加不回去动画不会重播
+  el.stage.classList.add('flashing', 'shaking');
+  setTimeout(() => el.stage.classList.remove('flashing'), 300);
+  setTimeout(() => el.stage.classList.remove('shaking'), 500);
+}
+
+async function playAwaken(id, { auto = false } = {}) {
+  const def = window.AWAKENS?.list?.[id];
+  if (!def || state.awakening) return false;
+  if (state.dragging || state.pressed) return false; // 手还按在角色上，等松手
+
+  const token = ++awakenToken;
+  state.autoAwaken = !!auto;
+  if (state.roaming) {
+    window.pet.haltRoam();
+    endLoco('awaken');
+  }
+  holdShow();
+
+  // 1) 先把屏幕压黑
+  FX.dim(def.dimAlpha, 170, def.palette.stroke);
+
+  // 2) 暗幕盖满之后再把窗口放大，同时按新窗口高度算「镜头推近」的倍数
+  await new Promise((r) => setTimeout(r, 180));
+  if (token !== awakenToken) return false;
+
+  let target = null;
+  try {
+    target = await window.pet.awakenOpen();
+  } catch {
+    target = null;
+  }
+  if (token !== awakenToken) return false;
+
+  const boxH = target?.height || window.innerHeight;
+  const curH = el.sprite.getBoundingClientRect().height || 1;
+  // 角色占画面 ~70% 高：上方要留出「台词 + 技能名」那条安全带。
+  // 不能再大了 —— 觉醒序列图里「举臂 + 光环」那种帧本身就比站姿高一大截。
+  const zoom = Math.max(1.05, Math.min(cfg.awaken?.stage?.zoom ?? 1.5, (boxH * 0.7) / curH));
+  el.stage.style.setProperty('--awaken-zoom', zoom.toFixed(3));
+  el.stage.classList.add('awakening');
+
+  // 战斗服序列帧（轻量档：只在演出里换）。分三个阶段找素材：
+  //   charge（蓄力序列）> burst（爆发序列）> still（旧版单帧立绘）> idle 帧
+  // 缺哪一段就退到下一级，光效不会因此少一块。
+  const sheet = def.sheet || {};
+  const phaseKey = (phase) => `awaken:${id}:${phase}`;
+  const hasPhase = (phase) => sheetStore.has(phaseKey(phase));
+  // 素材降级链：缺什么就用下一档，光效不会因此少一块
+  const anyArt = hasPhase('charge') || hasPhase('burst') || hasPhase('still');
+  const fallbackKey = () =>
+    hasPhase('charge') ? phaseKey('charge') : hasPhase('burst') ? phaseKey('burst') : hasPhase('still') ? phaseKey('still') : 'idle';
+  let curSheet = null;
+  const showFrame = (key, idx) => {
+    if (curSheet !== key) {
+      useSheet(key);
+      curSheet = key;
+    }
+    awakenFrame(idx);
+  };
+
+  // 起手：黑幕还没打开就先摆好第一帧，避免「幕布一淡开是 idle 站姿」
+  if (anyArt) showFrame(fallbackKey(), 0);
+  else useSheet('idle');
+  setAnim('idle');
+
+  const built = def.build({ fx: FX, point: awakenPoint });
+  const events = built.events.slice();
+
+  // 蓄力：暗幕从全黑提到 0.6（soft），让玩家真的能看到蓄力动作在演，
+  // 而不是从头到尾一层黑幕摆完五秒 —— 那多帧素材就白做了。
+  if (sheet.charge) {
+    events.push([sheet.charge.at, () => FX.dim(0.6, 420, def.palette.stroke, true)]);
+  }
+
+  // 逐帧排点：帧号写死在时间轴上，所以「动作推到哪一帧」和「特效炸在哪一刻」是对死的
+  const addFrames = (scope, phase) => {
+    if (!scope) return;
+    const key = hasPhase(phase) ? phaseKey(phase) : fallbackKey();
+    const count = key === 'idle' ? 1 : sheetStore.get(key).frames;
+    for (let i = 0; i < count; i++) {
+      events.push([
+        scope.at + i * scope.step,
+        () => {
+          if (token !== awakenToken) return;
+          showFrame(key, i);
+        },
+      ]);
+    }
+  };
+  addFrames(sheet.charge, 'charge');
+  addFrames(sheet.burst, 'burst');
+
+  events.push([def.revealAt, () => awakenReveal(token)]);
+  events.push([
+    def.closeAt,
+    () => {
+      if (token !== awakenToken) return;
+      FX.dim(def.dimAlpha, 240, def.palette.stroke);
+      // 窗口变回去这一帧同样藏在暗幕后面，所以这里可以放心地提前收
+      setTimeout(() => {
+        if (token !== awakenToken) return;
+        el.stage.classList.remove('awakening', 'flashing', 'shaking');
+        el.stage.style.removeProperty('--awaken-zoom');
+        useSheet('idle');
+        window.pet.awakenClose();
+      }, 260);
+    },
+  ]);
+  events.sort((a, b) => a[0] - b[0]);
+
+  FX.play(events, built.duration, () => {
+    if (token !== awakenToken) return;
+    FX.dim(0, 320, def.palette.stroke);
+    setTimeout(() => {
+      if (token !== awakenToken) return;
+      releaseShow();
+    }, 340);
+  });
+
+  dbg(`awaken-start id=${id} zoom=${zoom.toFixed(2)} box=${boxH} art=${curSheet || 'idle'}`);
+  return true;
+}
+
+/** 演出中途叫停（用户拖动 / 菜单 / HTTP /awaken/stop） */
+function stopAwaken() {
+  if (!state.awakening) return false;
+  awakenToken++; // 让所有挂起的回调失效
+  FX.reset();
+  window.pet.awakenClose();
+  releaseShow();
+  dbg('awaken-stop');
+  return true;
+}
+
+/* ------------------------------------------------------------ 交互事件 */
+
+function onPointerDown(e) {
+  if (e.button === 2) return;
+  // 演出期间用户上手 = 要收回画面，别跟他争
+  if (state.awakening) {
+    stopAwaken();
+    return;
+  }
+  const hit = hitTest(e.clientX, e.clientY);
+  dbg(
+    `pointerdown hit=${hit} client=${Math.round(e.clientX)},${Math.round(e.clientY)} screen=${e.screenX},${e.screenY}`,
+  );
+  if (!hit) return;
+
+  wake();
+  // 用户上手了，正在进行的巡游立即让位（主进程也会从 drag-start 那边兜一道）
+  if (state.roaming) {
+    window.pet.haltRoam();
+    endLoco('drag');
+  }
+  state.pressed = true;
+  state.movedFar = false;
+  state.dragDist = 0;
+  // 用屏幕坐标做阈值：窗口跟着光标移动时 client 坐标会失真
+  dragOrigin = { x: e.screenX, y: e.screenY };
+  lastPointer.sx = e.screenX;
+  lastPointer.sy = e.screenY;
+  moveTicks = 0;
+  try {
+    el.stage.setPointerCapture(e.pointerId);
+  } catch {
+    /* 忽略 */
+  }
+}
+
+function onPointerMove(e) {
+  lastPointer.x = e.clientX;
+  lastPointer.y = e.clientY;
+
+  // 1) 命中测试 -> 决定是否鼠标穿透
+  const now = performance.now();
+  if (now - lastHitCheck > 30) {
+    lastHitCheck = now;
+    if (state.pressed || state.dragging || cfg.clickThrough) {
+      // 拖拽中保持可交互
+    } else {
+      const hit = hitTest(e.clientX, e.clientY);
+      setInteractive(hit);
+      if (hit !== state.hover) {
+        state.hover = hit;
+        el.stage.classList.toggle('hovering', hit);
+        dbg(`hit-change hit=${hit} ${hitDebug(e.clientX, e.clientY)}`);
+      }
+    }
+  }
+
+  // 2) 拖拽窗口 + 摆动
+  if (state.pressed && dragOrigin) {
+    const dx = e.screenX - dragOrigin.x;
+    const dy = e.screenY - dragOrigin.y;
+    if (!state.movedFar && Math.hypot(dx, dy) > 4) {
+      state.movedFar = true;
+      state.dragging = true;
+      el.stage.classList.remove('hovering');
+      dbg(`drag-start screen=${e.screenX},${e.screenY}`);
+      window.pet.dragStart();
+      setAnim('drag');
+    }
+    if (state.dragging) {
+      // 用屏幕坐标算速度 -> 身体反向摆动，像被拎起来晃
+      const vx = e.screenX - lastPointer.sx;
+      lastPointer.sx = e.screenX;
+      lastPointer.sy = e.screenY;
+      state.dragDist = Math.max(state.dragDist, Math.hypot(dx, dy));
+      const tilt = Math.max(-16, Math.min(16, -vx * 2.2));
+      el.stage.style.setProperty('--tilt', `${tilt}deg`);
+      window.pet.dragMove();
+      if (moveTicks++ % 12 === 0) dbg(`drag-move screen=${e.screenX},${e.screenY}`);
+    }
+  }
+
+  // 3) 悬停时身体/眼神跟随（巡游中不跟，不然会和步态动画打架）
+  if (awake() && !busy()) {
+    const r = el.anchor.getBoundingClientRect();
+    const nx = (e.clientX - r.left) / r.width - 0.5;
+    const ny = (e.clientY - r.top) / r.height - 0.62;
+    // ×face：look 偏移是在 facer 里面做的，会被 scaleX 镜像，预纠正一下方向才对
+    const lookX = Math.max(-9, Math.min(9, nx * 16)) * state.face;
+    el.sprite.style.setProperty('--look-x', `${lookX}px`);
+    el.sprite.style.setProperty('--look-y', `${Math.max(-6, Math.min(6, ny * 10))}px`);
+    el.stage.style.setProperty('--lean', `${Math.max(-3, Math.min(3, nx * 5))}deg`);
+  }
+
+  if (awake()) resetIdleTimer();
+}
+
+function onPointerUp(e) {
+  if (e.button === 2) return;
+
+  const wasDragging = state.dragging;
+  const wasPressed = state.pressed;
+  dbg(`pointerup pressed=${wasPressed} dragging=${wasDragging} screen=${e.screenX},${e.screenY}`);
+
+  state.pressed = false;
+  state.dragging = false;
+  dragOrigin = null;
+
+  if (wasDragging) {
+    window.pet.dragEnd();
+    el.stage.style.setProperty('--tilt', '0deg');
+    // 手抖：按下后漂移不到 CLICK_SLOP 像素就松手，按单击处理，不然用户会觉得“点了没反应”
+    if (state.dragDist < CLICK_SLOP) {
+      dbg(`small-drag-as-click dist=${Math.round(state.dragDist)}`);
+      reactToClick();
+    } else {
+      setAnim('land', 520);
+    }
+    wake();
+    return;
+  }
+
+  if (wasPressed) reactToClick();
+}
+
+/** 单击反应：跳一下 + 甜妹台词 + 爱心 */
+function reactToClick() {
+  const line = pickLine();
+  dbg(`click-react "${line}"`);
+  setAnim('hop', 640);
+  setTimeout(() => {
+    if (!awake()) return;
+    spawnHearts(4 + Math.floor(Math.random() * 3));
+  }, 300);
+  say(line);
+  resetIdleTimer();
+}
+
+function onDblClick(e) {
+  if (!hitTest(e.clientX, e.clientY)) return;
+  clearTimeout(bubbleTimer);
+  el.bubble.classList.remove('show');
+  setAnim('dance', 2700);
+  spawnHearts(7);
+  say(['看我的必杀技～！', '嘿嘿，跳舞给你看！', '转圈圈～转圈圈～'][Math.floor(Math.random() * 3)]);
+}
+
+function onContextMenu(e) {
+  e.preventDefault();
+  if (!hitTest(e.clientX, e.clientY)) return;
+  wake();
+  window.pet.contextMenu();
+}
+
+function onWindowLeave() {
+  if (!state.pressed && !state.dragging) setInteractive(false);
+}
+
+/* ----------------------------------------------------------- 生命周期 */
+
+async function init() {
+  el.stage = document.getElementById('stage');
+  el.anchor = document.getElementById('anchor');
+  el.facer = document.getElementById('facer');
+  el.character = document.getElementById('character');
+  el.sprite = document.getElementById('sprite');
+  el.water = document.getElementById('water');
+  el.bubble = document.getElementById('bubble');
+  el.bubbleText = document.getElementById('bubble-text');
+  el.hearts = document.getElementById('hearts');
+  el.text = el.bubble;
+
+  FX.init(document.getElementById('fx'));
+
+  cfg = await window.pet.getConfig();
+  dbgOn = !!cfg.debug;
+  gapOverride = cfg.roamGapMs || null;
+  dbg(`init debug=${dbgOn} roamGap=${gapOverride ?? '默认区间'}`);
+  state.scale = cfg.scale ?? 1;
+  applyScale(state.scale);
+
+  // 先把所有精灵图加载完，后续切动作就是纯 CSS 替换
+  await preloadSheets();
+  useSheet('idle');
+
+  document.addEventListener('pointerdown', onPointerDown);
+  document.addEventListener('pointermove', onPointerMove);
+  document.addEventListener('pointerup', onPointerUp);
+  document.addEventListener('pointercancel', onPointerUp);
+  document.addEventListener('dblclick', onDblClick);
+  document.addEventListener('contextmenu', onContextMenu);
+  document.addEventListener('mouseleave', onWindowLeave);
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape') window.pet.setScale(1);
+  });
+
+  window.pet.onSay((payload) => say(payload.text, { mood: payload.mood }));
+  window.pet.onAction(({ name }) => {
+    if (name === 'awaken-stop') {
+      stopAwaken();
+      return;
+    }
+    // 演出期间别的动作一律丢掉，不然会把觉醒的动画顶掉
+    if (state.awakening) return;
+    if (name.startsWith('awaken:')) {
+      playAwaken(name.slice('awaken:'.length)).catch(() => {});
+      return;
+    }
+    if (name === 'greet') {
+      setAnim('hop', 640);
+      say('你好呀～我是你的桌面小助手！');
+      spawnHearts(4);
+    } else if (name === 'dance') {
+      setAnim('dance', 2700);
+      spawnHearts(6);
+      say('Music—— start!');
+    } else if (name === 'sleep') {
+      if (state.roaming) {
+        window.pet.haltRoam();
+        endLoco('sleep');
+      }
+      state.sleeping = true;
+      el.stage.classList.add('sleeping');
+      setAnim('sleep');
+    } else if (name === 'walk' || name === 'run' || name === 'swim') {
+      // 菜单 / HTTP 明确点名：可以插队打断当前动画
+      doRoam(name, { force: true }).catch(() => {});
+    } else if (name === 'stop') {
+      window.pet.haltRoam();
+      endLoco('halt');
+    }
+  });
+  window.pet.onLocoEnd(({ reason }) => {
+    if (reason === 'restart') return; // 主进程紧接着会发新的一段，让它自己接管
+    endLoco(reason);
+  });
+  window.pet.onAuto(({ enabled }) => {
+    cfg.autoRoam = enabled;
+    if (!enabled) {
+      window.pet.haltRoam();
+      endLoco('halt');
+    }
+    scheduleRoam(1500);
+  });
+  window.pet.onDemo(({ anim }) => applyDemo(anim));
+  window.pet.onPollHit(({ x, y }) => {
+    if (state.pressed || state.dragging || !awake()) return;
+    const hit = hitTest(x, y);
+    if (hit) {
+      setInteractive(true);
+      dbg(`poll-hit wake ${hitDebug(x, y)}`);
+    }
+  });
+  window.pet.onScale((s) => {
+    state.scale = s;
+    applyScale(s);
+    // 尺寸变了精灵图要重新算显示像素；演出中窗口由主进程控，别在这时候重算
+    if (!state.awakening) useSheet(state.sheetKey || 'idle');
+  });
+
+  // 首次使用给个小提示
+  el.stage.classList.add('hinting');
+  setTimeout(() => el.stage.classList.remove('hinting'), 3500);
+
+  scheduleBlink();
+  scheduleMicro();
+  scheduleRoam();
+  resetIdleTimer();
+  setAnim('idle');
+
+  greetTimer = setTimeout(() => say('我在这里哦～点我试试！'), 700);
+}
+
+function applyScale(scale) {
+  state.scale = scale;
+  el.stage.style.setProperty('--pet-scale', scale);
+}
+
+/** 素材缺失时的兜底角色（内联 SVG，不依赖外部文件） */
+function placeholderCharacter() {
+  const svg = `
+<svg xmlns="http://www.w3.org/2000/svg" width="240" height="360" viewBox="0 0 240 360">
+  <ellipse cx="120" cy="345" rx="58" ry="10" fill="rgba(80,50,80,0.25)"/>
+  <path d="M62 190 Q40 130 78 92 Q120 52 162 92 Q200 130 178 190 Z" fill="#ffd0e4"/>
+  <circle cx="120" cy="120" r="62" fill="#ffe3ef" stroke="#e79dc0" stroke-width="4"/>
+  <path d="M58 108 Q70 52 120 48 Q170 52 182 108 Q150 84 120 84 Q90 84 58 108Z" fill="#ffc2dd" stroke="#e79dc0" stroke-width="3"/>
+  <circle cx="98" cy="126" r="11" fill="#3a2b46"/><circle cx="142" cy="126" r="11" fill="#3a2b46"/>
+  <circle cx="102" cy="121" r="4" fill="#fff"/><circle cx="146" cy="121" r="4" fill="#fff"/>
+  <path d="M106 152 Q120 164 134 152" stroke="#c96b95" stroke-width="4" fill="none" stroke-linecap="round"/>
+  <path d="M64 176 Q120 214 176 176 L188 300 Q120 322 52 300 Z" fill="#b8e6d5" stroke="#8fcbb6" stroke-width="4"/>
+</svg>`;
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
+
+init();