arona-agent 1.0.0

package/pet/main.cjs

@@ -0,0 +1,462 @@
+// ARONA 桌宠 Electron 主进程
+// 与主 Agent 进程通过 stdin/stdout JSON lines 通信（协议行前缀 ###PET### 过滤 Electron 日志）
+// 支持多角色同屏：ARONA_AGENT = 主 Agent，ARONA_SUB_AGENTS = 逗号分隔的子 Agent 列表；
+// 每个角色一个 BrowserWindow，共享一个全屏特效窗。
+const { app, BrowserWindow, ipcMain, screen } = require("electron");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+const { AGENTS } = require("./agents.cjs");
+
+// Windows 透明无边框窗口在部分显卡驱动下会触发渲染进程崩溃；禁 GPU 硬件加速（须在 app ready 前调用）。
+// 注意：不能用 app.disableHardwareAcceleration()——Electron 43 里它会顺带 --disable-software-rasterizer，
+// 把软件 WebGL 一并堵死（实测 getGPUFeatureStatus().webgl === "disabled_off"，Spine 直接白屏）。
+// 改用细粒度 flag：disable-gpu 只禁硬件 GPU（保留"防透明窗口崩溃"的初衷），
+// enable-unsafe-swiftshader 放行 SwiftShader 软件 WebGL（仍失败则 spine_layer 自动降级 Canvas 2D，见 §B12）。
+if (process.platform === "win32") {
+  app.commandLine.appendSwitch("disable-gpu");
+  app.commandLine.appendSwitch("enable-unsafe-swiftshader");
+}
+
+// 角色选择：主 Agent + 子 Agent 列表
+const MAIN_AGENT_ID = process.env.ARONA_AGENT && AGENTS[process.env.ARONA_AGENT] ? process.env.ARONA_AGENT : "arona";
+const SUB_AGENT_IDS = (process.env.ARONA_SUB_AGENTS || "")
+  .split(",")
+  .map((s) => s.trim())
+  .filter((s) => s && AGENTS[s]);
+const AGENT_IDS = [MAIN_AGENT_ID, ...SUB_AGENT_IDS];
+
+const PREFIX = "###PET###";
+const POS_FILE = path.join(os.homedir(), ".arona", "pet.json");
+const WIN_W = 580; // 窗口总宽：左侧 320px 为 Spine 角色渲染区，右侧 260px 为文字气泡专用区（避免气泡遮脸）
+const WIN_H = 674;
+const SUB_OFFSET_X = 620; // 子窗口默认横向错开（> WIN_W，避免角色+气泡区重叠）
+const SUB_OFFSET_Y = 40;
+
+// --verbose（src/pet.ts 注入 ARONA_PET_VERBOSE=1 + --enable-logging）：
+// 主进程详细日志走 stderr 原样转发回终端，用于锁定 Windows 白屏等"进程活着但无画面"问题。
+const VERBOSE = process.env.ARONA_PET_VERBOSE === "1";
+function vlog(...args) {
+  if (VERBOSE) console.error("[pet:verbose]", ...args);
+}
+
+/** agentId -> BrowserWindow；主 Agent 始终在列表首位 */
+const petWins = new Map();
+let fxWin = null; // 全屏透明特效窗口（点击/拖尾），覆盖所有显示器、鼠标穿透
+
+function send(msg) {
+  try {
+    process.stdout.write(PREFIX + JSON.stringify(msg) + "\n");
+  } catch {
+    // stdout 已关闭，忽略
+  }
+}
+
+// ---- 位置记忆（多角色格式：{ [agentId]: { x, y } }；兼容旧 { x, y } → arona） ----
+function loadPositions() {
+  try {
+    const data = JSON.parse(fs.readFileSync(POS_FILE, "utf-8"));
+    if (data && typeof data === "object" && !Array.isArray(data)) return data;
+  } catch {
+    // 无记录或损坏，忽略
+  }
+  return {};
+}
+
+function loadPosition(agentId) {
+  const data = loadPositions();
+  let pos = data[agentId];
+  // 旧版单角色格式兼容迁移：{x,y} 视为 arona 的位置
+  if (!pos && agentId === MAIN_AGENT_ID && Number.isFinite(data.x) && Number.isFinite(data.y)) {
+    pos = { x: data.x, y: data.y };
+  }
+  if (!pos || !Number.isFinite(pos.x) || !Number.isFinite(pos.y)) return null;
+  // 屏幕边界检查：记忆坐标须落在任一显示器 bounds 内（中心点判定），否则视为失效。
+  // 防分辨率变化 / Mac→Win 迁移 / 负坐标导致窗口创建在屏幕外"看似没显示"。
+  const W = WIN_W, H = WIN_H;
+  for (const d of screen.getAllDisplays()) {
+    const { x, y, width, height } = d.bounds;
+    const cx = pos.x + W / 2, cy = pos.y + H / 2;
+    if (cx >= x && cx <= x + width && cy >= y && cy <= y + height) return pos;
+  }
+  return null;
+}
+
+function savePosition(agentId, x, y) {
+  try {
+    const data = loadPositions();
+    // 旧版 {x,y} 迁移：一旦保存新格式，就不再有顶层 x/y
+    delete data.x;
+    delete data.y;
+    data[agentId] = { x, y };
+    fs.mkdirSync(path.dirname(POS_FILE), { recursive: true });
+    fs.writeFileSync(POS_FILE, JSON.stringify(data, null, 2));
+  } catch {
+    // 写入失败不影响功能
+  }
+}
+
+// ---- 窗口 ----
+function defaultPosition(index) {
+  if (index === 0) return null;
+  // 找不到记忆坐标时使用相对主显示器的默认错开位（macOS 菜单栏下方安全区起步）
+  const primary = screen.getPrimaryDisplay().bounds;
+  return {
+    x: primary.x + 40 + SUB_OFFSET_X * (index - 1),
+    y: primary.y + 80 + SUB_OFFSET_Y * (index - 1),
+  };
+}
+
+function createPetWindow(agentId, index) {
+  const agent = AGENTS[agentId];
+  const bw = new BrowserWindow({
+    width: WIN_W,
+    height: WIN_H,
+    transparent: true,
+    frame: false,
+    hasShadow: false,
+    alwaysOnTop: true,
+    skipTaskbar: true,
+    resizable: false,
+    focusable: false, // 不抢终端焦点
+    webPreferences: {
+      preload: path.join(__dirname, "preload.cjs"),
+      contextIsolation: true,
+      nodeIntegration: false,
+    },
+  });
+  bw.setAlwaysOnTop(true, "screen-saver");
+  if (process.platform === "darwin") {
+    bw.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+  }
+  const pos = loadPosition(agentId) || defaultPosition(index);
+  if (pos) bw.setPosition(pos.x, pos.y);
+  vlog("window created", JSON.stringify({ agentId, pos, alwaysOnTop: bw.isAlwaysOnTop(), visible: bw.isVisible(), bounds: bw.getBounds() }));
+
+  // PET_PAGE=spinetest → 加载 Spine 调试页（默认仍 index.html，零风险）
+  const page = process.env.PET_PAGE === "spinetest" ? "spinetest.html" : "index.html";
+  // ?agent=<id>：渲染层（spine_layer.js/renderer.js）据此读取对应角色配置
+  const url = path.join(__dirname, "renderer", page);
+  bw.loadFile(url, { search: "agent=" + agentId });
+  vlog("loadFile", url, "?agent=" + agentId);
+  if (process.env.PET_PAGE) {
+    // 调试页：附带 devtools 便于人工查看 console / 网络加载
+    bw.webContents.openDevTools({ mode: "detach" });
+  }
+  bw.webContents.on("did-finish-load", () => {
+    vlog("did-finish-load", bw.webContents.getURL());
+    send({ type: "ready", agent: agentId });
+  });
+  // ---- GL 驱动消息缓冲 / 报错解锁（2026-08-20）----
+  // Windows SwiftShader 下 Chromium 把 GL 驱动性能提示（如
+  // "GPU stall due to ReadPixels"，Chromium gl_utils.cc 的 Performance 级消息）
+  // 作为 console 消息打到渲染进程。非 verbose 时是纯噪音——平时静默缓冲；
+  // 一旦程序真报错（error 级 console / did-fail-load / render-process-gone），
+  // 补打缓冲行并解锁后续不过滤，保住排障信息。VERBOSE 全量输出不走此逻辑。
+  const GL_DRIVER_MSG = "GL Driver Message";
+  let glDroppedBuf = []; // 被过滤的 GL 驱动消息（环形，上限 20）
+  let glUnlocked = false; // 报错后不再过滤
+  const unlockGlLogs = () => {
+    if (glUnlocked) return;
+    glUnlocked = true;
+    if (glDroppedBuf.length) {
+      for (const m of glDroppedBuf) console.error(`[pet:render:${agentId}] ${m}`);
+      glDroppedBuf = [];
+    }
+  };
+  // 页面加载失败（资源 404 / file:// 路径错 / 加载被拦）：必然白屏，任何模式都要转发
+  bw.webContents.on("did-fail-load", (_e, code, desc, url2, isMain) => {
+    if (!isMain) return;
+    unlockGlLogs();
+    console.error(`[pet:render] did-fail-load agent=${agentId} code=${code} desc=${desc} url=${url2}`);
+  });
+  // renderer console 转发到 stderr（src/pet.ts 已打印 [pet] 前缀）：页面 JS 错误默认静默
+  // （不进 stderr），Windows 白屏等故障全靠它定位。Electron 43 规范签名为单事件对象：
+  // event.{message, level, lineNumber, sourceId}（老双参数签名会打 deprecation 警告）。
+  bw.webContents.on("console-message", (event) => {
+    const msg = typeof event.message === "string" ? event.message : "";
+    if (!msg) return;
+    const line = event.lineNumber ? `:${event.lineNumber}` : "";
+    if (VERBOSE) {
+      const src = event.sourceId ? ` (${event.sourceId}${line})` : "";
+      console.error(`[pet:render:${event.level ?? "?"}:${agentId}]${src} ${msg}`);
+      return;
+    }
+    // 非 verbose：严格判断——GL 驱动性能提示平时静默，仅报错后放行
+    if (event.level === 3) {
+      unlockGlLogs(); // 报错：补打被缓冲的 GL 消息，之后不再过滤
+      console.error(`[pet:render:${agentId}]${line} ${msg}`);
+      return;
+    }
+    if (!glUnlocked && msg.includes(GL_DRIVER_MSG)) {
+      if (glDroppedBuf.length >= 20) glDroppedBuf.shift();
+      glDroppedBuf.push(msg);
+      return;
+    }
+    console.error(`[pet:render:${agentId}]${line} ${msg}`);
+  });
+  // 渲染进程崩溃上报（Windows 透明窗口崩溃的主因；reason/exitCode 可精确定位）
+  bw.webContents.on("render-process-gone", (_e, details) => {
+    unlockGlLogs();
+    send({ type: "crash", agent: agentId, kind: "render", reason: details.reason, exitCode: details.exitCode, url: bw.webContents.getURL() });
+    vlog("render-process-gone", JSON.stringify({ agentId, ...details }));
+  });
+  // 窗口关闭诊断（verbose）：window-all-closed 会因任一窗口被系统/驱动关闭而触发，导致 code 0 退出
+  bw.on("closed", () => {
+    vlog("window closed", agentId);
+    petWins.delete(agentId);
+  });
+  petWins.set(agentId, bw);
+}
+
+// ---- 全屏特效窗口（点击/拖尾铺满整个屏幕） ----
+// 覆盖所有显示器的并集 bounds；透明、鼠标穿透（setIgnoreMouseEvents），
+// 层级高于桌宠（screen-saver + 1），这样拖尾能盖在角色之上跨屏延伸。
+function getAllDisplaysBounds() {
+  const ds = screen.getAllDisplays();
+  if (!ds.length) return screen.getPrimaryDisplay().bounds;
+  let x = Infinity, y = Infinity, x2 = -Infinity, y2 = -Infinity;
+  for (const d of ds) {
+    x = Math.min(x, d.bounds.x);
+    y = Math.min(y, d.bounds.y);
+    x2 = Math.max(x2, d.bounds.x + d.bounds.width);
+    y2 = Math.max(y2, d.bounds.y + d.bounds.height);
+  }
+  return { x, y, width: x2 - x, height: y2 - y };
+}
+
+function createFxWindow() {
+  const b = getAllDisplaysBounds();
+  fxWin = new BrowserWindow({
+    x: b.x,
+    y: b.y,
+    width: b.width,
+    height: b.height,
+    transparent: true,
+    frame: false,
+    hasShadow: false,
+    alwaysOnTop: true,
+    skipTaskbar: true,
+    resizable: false,
+    focusable: false,
+    fullscreenable: false,
+    webPreferences: {
+      preload: path.join(__dirname, "preload.cjs"),
+      contextIsolation: true,
+      nodeIntegration: false,
+    },
+  });
+  fxWin.setAlwaysOnTop(true, "screen-saver", 1); // 高于桌宠窗口的 screen-saver
+  fxWin.setIgnoreMouseEvents(true); // 鼠标穿透，不拦任何点击
+  if (process.platform === "darwin") {
+    fxWin.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+  }
+  fxWin.loadFile(path.join(__dirname, "renderer", "fx.html"));
+  fxWin.on("closed", () => vlog("fxWin closed"));
+  vlog("fx window created", JSON.stringify({ x: b.x, y: b.y, width: b.width, height: b.height }));
+}
+
+// ---- 工具：根据 webContents 找所属 agent ----
+function agentBySender(sender) {
+  for (const [agentId, bw] of petWins) {
+    if (bw.webContents === sender) return agentId;
+  }
+  return MAIN_AGENT_ID;
+}
+
+function windowByAgent(agentId) {
+  return petWins.get(agentId) || null;
+}
+
+// ---- 特效坐标转发：桌宠窗口(全局 DIP) → 特效窗口(本地 CSS px) ----
+// screenX/screenY 是相对主显示器原点的全局 DIP，减去 fxWin 左上角即得本地坐标。
+function relayFx(channel, sx, sy) {
+  if (!fxWin || fxWin.isDestroyed()) return;
+  const [wx, wy] = fxWin.getPosition();
+  fxWin.webContents.send(channel, sx - wx, sy - wy);
+}
+
+ipcMain.on("pet:fx-down", (_e, sx, sy) => relayFx("fx:down", sx, sy));
+ipcMain.on("pet:fx-move", (_e, sx, sy) => relayFx("fx:move", sx, sy));
+ipcMain.on("pet:fx-up", () => {
+  if (fxWin && !fxWin.isDestroyed()) fxWin.webContents.send("fx:up");
+});
+
+// ---- 全局光标轮询（~60Hz，DIP 坐标系内运算，供渲染层瞳孔跟随 + 按住期间晃动检测补采样） ----
+// 对每个桌宠窗口分别发送窗口本地坐标 + 全局坐标（gx/gy：renderer 按住期间用于晃动检测——
+// 光标快速甩动划出窗口时 mousemove 断流，本轮询不断流，轻微出窗仍能采到晃动）
+const CURSOR_POLL_MS = 16;
+let cursorTimer = null;
+const lastCursors = new Map();
+
+function startCursorTracking() {
+  if (cursorTimer) return;
+  cursorTimer = setInterval(() => {
+    const p = screen.getCursorScreenPoint();      // 全局 DIP
+    for (const [agentId, bw] of petWins) {
+      if (bw.isDestroyed() || !bw.isVisible()) continue;
+      const [wx, wy] = bw.getPosition();
+      const x = p.x - wx;
+      const y = p.y - wy;                         // 窗口本地 CSS px（可在窗口外，注视效果所需）
+      const last = lastCursors.get(agentId);
+      if (Math.abs(x - (last?.x ?? NaN)) < 1 && Math.abs(y - (last?.y ?? NaN)) < 1) continue; // 静止节流
+      lastCursors.set(agentId, { x, y });
+      bw.webContents.send("pet:cursor", x, y, p.x, p.y);
+    }
+  }, CURSOR_POLL_MS);
+}
+
+// ---- 拖动 IPC（16ms 节流，按窗口独立） ----
+const dragPendingMap = new Map();
+const dragTimerMap = new Map();
+
+ipcMain.on("pet:drag", (e, dx, dy) => {
+  const agentId = agentBySender(e.sender);
+  const bw = windowByAgent(agentId);
+  if (!bw) return;
+  const prev = dragPendingMap.get(agentId) || { x: bw.getPosition()[0], y: bw.getPosition()[1] };
+  const pending = { x: prev.x + dx, y: prev.y + dy };
+  dragPendingMap.set(agentId, pending);
+  if (!dragTimerMap.has(agentId)) {
+    dragTimerMap.set(agentId, setTimeout(() => {
+      dragTimerMap.delete(agentId);
+      const p = dragPendingMap.get(agentId);
+      if (p && windowByAgent(agentId)) {
+        windowByAgent(agentId).setPosition(Math.round(p.x), Math.round(p.y));
+        dragPendingMap.delete(agentId);
+      }
+    }, 16));
+  }
+});
+
+ipcMain.on("pet:dragend", (e) => {
+  const agentId = agentBySender(e.sender);
+  const bw = windowByAgent(agentId);
+  if (!bw) return;
+  const timer = dragTimerMap.get(agentId);
+  if (timer) {
+    clearTimeout(timer);
+    dragTimerMap.delete(agentId);
+  }
+  const pending = dragPendingMap.get(agentId);
+  if (pending) {
+    bw.setPosition(Math.round(pending.x), Math.round(pending.y));
+    dragPendingMap.delete(agentId);
+  }
+  const [x, y] = bw.getPosition();
+  savePosition(agentId, x, y);
+  send({ type: "moved", agent: agentId, x, y });
+});
+
+ipcMain.on("pet:shake", (e) => send({ type: "shake", agent: agentBySender(e.sender) }));
+ipcMain.on("pet:dizzy", (e) => send({ type: "dizzy", agent: agentBySender(e.sender) }));
+
+ipcMain.handle("pet:get-agent-config", (e) => {
+  const agentId = agentBySender(e.sender);
+  // isMain：renderer 据此让"仅主 Agent 响应"的交互（大幅晃动 dizzy）跳过子窗口
+  return { id: agentId, isMain: agentId === MAIN_AGENT_ID, ...AGENTS[agentId] };
+});
+
+// ---- stdin 协议 ----
+let buffer = "";
+
+function sendToAgent(agentId, channel, payload) {
+  const bw = windowByAgent(agentId);
+  if (!bw || bw.isDestroyed()) return false;
+  bw.webContents.send(channel, payload);
+  return true;
+}
+
+function handleMessage(msg) {
+  vlog("stdin msg", JSON.stringify(msg));
+  switch (msg.type) {
+    case "set_emotion": {
+      const id = msg.agent && AGENTS[msg.agent] ? msg.agent : MAIN_AGENT_ID;
+      if (AGENTS[id].emotions[msg.name]) {
+        if (!sendToAgent(id, "pet:emotion", msg.name)) send({ type: "error", message: `no window for ${id}` });
+      } else {
+        send({ type: "error", message: `unknown emotion: ${msg.name}` });
+      }
+      break;
+    }
+    case "reset":
+      // 所有角色窗口统一恢复默认待机
+      for (const [id] of petWins) sendToAgent(id, "pet:reset", null);
+      break;
+    case "text": {
+      const id = msg.agent && AGENTS[msg.agent] ? msg.agent : MAIN_AGENT_ID;
+      sendToAgent(id, "pet:text", { kind: msg.kind, data: msg.data });
+      break;
+    }
+    case "quit":
+      app.quit();
+      break;
+  }
+}
+
+process.stdin.on("data", (data) => {
+  buffer += data.toString();
+  const lines = buffer.split("\n");
+  buffer = lines.pop() || "";
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      handleMessage(JSON.parse(trimmed));
+    } catch {
+      // 非 JSON 行，忽略
+    }
+  }
+});
+
+process.stdin.on("end", () => {
+  // Windows：stdin 会提前 EOF（GUI 子系统 + 父进程 stdio 链），直接 app.quit() 会把刚启动、
+  // 尚未 did-finish-load 的桌宠误杀（症状：code 0 静默退出、窗口闪一下不见）。
+  // 桌宠退出由父进程（src/pet.ts）的 quit 指令 + SIGTERM 兜底驱动，不依赖 stdin EOF。
+  // 其他平台：stdin EOF 可靠表示父进程退出，跟随退出防孤儿进程。
+  vlog("stdin END", process.platform === "win32" ? "(ignored on win32)" : "(quit)");
+  if (process.platform !== "win32") app.quit();
+});
+
+app.whenReady().then(() => {
+  if (VERBOSE) {
+    // GPU 功能状态：确认 webgl/webgl2 是 hardware/software/disabled（Windows 白屏排查关键）
+    try {
+      vlog("GPU feature status:", JSON.stringify(app.getGPUFeatureStatus()));
+    } catch (e) {
+      vlog("getGPUFeatureStatus failed:", e.message);
+    }
+    vlog("platform:", process.platform, "electron:", process.versions.electron, "chrome:", process.versions.chrome);
+    vlog("displays:", JSON.stringify(screen.getAllDisplays().map((d) => d.bounds)));
+    vlog("agents:", JSON.stringify(AGENT_IDS));
+  }
+  AGENT_IDS.forEach((id, i) => createPetWindow(id, i));
+  createFxWindow();
+  startCursorTracking();
+});
+
+app.on("window-all-closed", () => {
+  vlog("window-all-closed → app.quit()");
+  if (cursorTimer) {
+    clearInterval(cursorTimer);
+    cursorTimer = null;
+  }
+  app.quit();
+});
+
+// 退出链路诊断（verbose）：定位"进程 code 0 退出但无 did-finish-load"的退出源
+app.on("before-quit", () => vlog("before-quit"));
+app.on("will-quit", () => vlog("will-quit"));
+
+// ---- 崩溃日志：GPU/utility 子进程崩溃 + 主进程 JS 异常（配合 src/pet.ts 的 crash 处理定位问题） ----
+app.on("child-process-gone", (_e, details) => {
+  send({ type: "crash", kind: details.type || "child", reason: details.reason, exitCode: details.exitCode });
+  vlog("child-process-gone", JSON.stringify(details));
+});
+process.on("uncaughtException", (err) => {
+  console.error("[pet:crash] uncaughtException:", err && err.stack ? err.stack : err);
+  process.exit(1); // 主进程状态已不可靠，退出让父进程按崩溃路径重启
+});
+process.on("unhandledRejection", (reason) => {
+  console.error("[pet:crash] unhandledRejection:", reason);
+});

package/pet/preload.cjs

@@ -0,0 +1,21 @@
+const { contextBridge, ipcRenderer } = require("electron");
+
+contextBridge.exposeInMainWorld("petAPI", {
+  onEmotion: (cb) => ipcRenderer.on("pet:emotion", (_e, name) => cb(name)),
+  onReset: (cb) => ipcRenderer.on("pet:reset", () => cb()),
+  onText: (cb) => ipcRenderer.on("pet:text", (_e, p) => cb(p)),
+  getAgentConfig: () => ipcRenderer.invoke("pet:get-agent-config"),
+  drag: (dx, dy) => ipcRenderer.send("pet:drag", dx, dy),
+  dragEnd: () => ipcRenderer.send("pet:dragend"),
+  shake: () => ipcRenderer.send("pet:shake"),
+  dizzy: () => ipcRenderer.send("pet:dizzy"),
+  // gx/gy：全局屏幕坐标（按住期间 renderer 用于晃动检测补采样，出窗不断流）
+  onCursor: (cb) => ipcRenderer.on("pet:cursor", (_e, x, y, gx, gy) => cb(x, y, gx, gy)),
+  // 点击/拖尾特效：桌宠窗口发全局屏幕坐标 → 主进程 → 全屏特效窗口收
+  fxDown: (x, y) => ipcRenderer.send("pet:fx-down", x, y),
+  fxMove: (x, y) => ipcRenderer.send("pet:fx-move", x, y),
+  fxUp: () => ipcRenderer.send("pet:fx-up"),
+  onFxDown: (cb) => ipcRenderer.on("fx:down", (_e, x, y) => cb(x, y)),
+  onFxMove: (cb) => ipcRenderer.on("fx:move", (_e, x, y) => cb(x, y)),
+  onFxUp: (cb) => ipcRenderer.on("fx:up", () => cb()),
+});

package/pet/renderer/fx.html

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'self' file: data: blob:; script-src 'self' file:; style-src 'self' 'unsafe-inline'; img-src 'self' file: data: blob:; font-src 'self' file:; connect-src 'self' file: data: blob:">
+  <style>
+    html, body {
+      margin: 0;
+      padding: 0;
+      width: 100%;
+      height: 100%;
+      background: transparent;
+      overflow: hidden;
+    }
+    /* 全屏特效画布：不拦截鼠标（manual 输入 + 主进程穿透），透明背景 */
+    #fx {
+      position: absolute;
+      inset: 0;
+      width: 100%;
+      height: 100%;
+      pointer-events: none;
+    }
+  </style>
+</head>
+<body>
+  <div id="fx"></div>
+  <script src="../../node_modules/ba-click-fx/dist/ba-click-fx.iife.js"></script>
+  <script src="fx.js"></script>
+</body>
+</html>

package/pet/renderer/fx.js

@@ -0,0 +1,41 @@
+// ARONA 全屏特效渲染层：ba-click-fx（manual 输入），覆盖整个屏幕画点击特效 + 拖尾。
+// 桌宠窗口只负责检测「窗口内长按拖动」，主进程把全局屏幕坐标转发到这里。
+// 透明窗口关键：outputCompositing 'browser-overlay' + hostCompositingSurface 'transparent-window'。
+let fx = null;
+
+function initFx() {
+  if (typeof BAClickFX === "undefined") return;
+  try {
+    fx = new BAClickFX.BAClickFX({
+      target: "#fx",
+      inputSource: "manual",
+      effectBackend: "webgl2",
+      bloomBackend: "webgl2",
+      outputCompositing: "browser-overlay",
+      overlayAlphaPolicy: "coverage",
+      overlayColorCompensation: "none",
+      overlayAlphaLimit: 250 / 255,
+      hostCompositing: "source-over",
+      hostCompositingSurface: "transparent-window",
+      lightBackgroundContrastAlpha: 0,
+      clickEnabled: true,
+      trailEnabled: true,
+      trailAlways: false,
+    });
+  } catch {
+    fx = null;
+  }
+}
+
+// 主进程已把全局屏幕坐标换算成本窗口（全屏覆盖）本地 CSS px，这里直接喂给 fx。
+window.petAPI.onFxDown((x, y) => {
+  if (fx) fx.pointerDown({ x, y, pointerId: 1, pointerType: "mouse" });
+});
+window.petAPI.onFxMove((x, y) => {
+  if (fx) fx.pointerMove({ x, y, pointerId: 1, pointerType: "mouse" });
+});
+window.petAPI.onFxUp(() => {
+  if (fx) fx.pointerUp(1);
+});
+
+initFx();

package/pet/renderer/gallery.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'self' file: data: blob:; script-src 'self' file:; style-src 'self' 'unsafe-inline'; img-src 'self' file: data: blob:; font-src 'self' file:; connect-src 'self' file: data: blob:">
+  <title>Spine 表情目视图库</title>
+  <style>
+    html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; background: transparent; }
+    #spine { position: absolute; inset: 0; width: 100%; height: 100%; }
+  </style>
+</head>
+<body>
+  <canvas id="spine"></canvas>
+  <script src="../vendor/spine/spine-webgl.js"></script>
+  <script src="spine_layer.js"></script>
+  <script src="gallery.js"></script>
+</body>
+</html>

package/pet/renderer/gallery.js

@@ -0,0 +1,31 @@
+// 表情目视图库（gallery.js）：加载当前 Agent 骨架，逐帧切换数字情绪预设，供人工目视选号。
+// 由 pet/tools/gallery_capture.cjs 驱动截图。
+// 与 spinetest 不同：这里不调度眨眼/注视/拖动，保证截图干净。
+// 注意：截图内不带任何水印（旧 #label 水印已删——DOM 文本与 WebGL 画布是两条合成路径，
+// 曾出现水印滞后于骨架的过期纹理帧，编号与脸错位误导选号；编号一律以 gallery.html 文字为准）。
+const canvas = document.getElementById("spine");
+
+async function init() {
+  await window.SpineLayer.init(canvas);
+  // 冻结 track0 Idle_01 相位：不同截图/不同批次身体姿势完全一致，可像素级对比（编号↔脸一一对应）
+  window.SpineLayer.pinBody(1.0);
+  window.__gallery = {
+    /**
+     * 切换到指定预设（数字动画名）。
+     * 数字预设 3.333s 非循环、残留末帧持有 → 外部按 settledMs 节奏等动画落定后再截图。
+     */
+    show(name) {
+      window.SpineLayer.setEmotionPreset(String(name), false, true);
+    },
+    /** 情绪确认模式：按情绪名渲染其映射预设 */
+    showEmotion(_emotionName, preset) {
+      window.SpineLayer.setEmotionPreset(String(preset), false, true);
+    },
+    /** 数字预设动画时长 + 余量（等落定到末帧——settled face 才是表情本体，见 CLAUDE.md B5） */
+    settledMs: 3600,
+  };
+}
+
+init().catch((err) => {
+  console.error("gallery init failed:", err);
+});

package/pet/renderer/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'self' file: data: blob:; script-src 'self' file:; style-src 'self' 'unsafe-inline'; img-src 'self' file: data: blob:; font-src 'self' file:; connect-src 'self' file: data: blob:">
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <div id="stage">
+    <canvas id="spine"></canvas>
+    <div id="pet-bubble" class="hidden"></div>
+  </div>
+  <script src="../vendor/spine/spine-webgl.js"></script>
+  <script src="../vendor/spine/spine-canvas.js"></script>
+  <script src="spine_layer.js"></script>
+  <script src="renderer.js"></script>
+</body>
+</html>