@mingxy/opencode-mascot 0.5.9 → 0.7.0

package/README.md

@@ -6,16 +6,25 @@ Customizable ASCII mascots that breathe, walk, sleep, get launched across the sc
 
 [English](./README.md) | [简体中文](./README_zh-CN.md)
 
+## 🏠 Home Page
+
+![home demo](./assets/demo-home.gif)
+
+## 💼 Work Page
+
+![work demo](./assets/demo-work.gif)
+
 ---
 
 ## ✨ Features
 
-### 🎭 Built-in Characters (2)
+### 🎭 Built-in Characters (3)
 
 | Character | Description | Color |
 |-----------|-------------|-------|
 | **yueer** | Purple-haired girl with an ahoge, tsundere style, default mascot | `#8B7EB8` lavender |
 | **baozi** | A steaming hot bun, warm and cozy | `#D4885A` warm orange |
+| **cat** | Orange tabby cat — purring, kneading, tail-swishing | `#FFA500` orange |
 
 Each character includes **5 expression frames**: default / blink / happy / thinking / sleeping
 
@@ -54,6 +63,17 @@ Each character includes **5 expression frames**: default / blink / happy / think
 | 15 | Alien text bubble | busy/thinking | 12 alien-text phrases rotate |
 | 16 | Drag panic | While dragging | `( °□° )` |
 
+**cat exclusive:**
+
+| # | Animation | Trigger | Effect |
+|---|-----------|---------|--------|
+| 17 | Tail swish | Every 0.6s | Tail `|_)` ↔ `|~)` |
+| 18 | Ear twitch | Random (20% / 2.5s) | Ear `/\` → `/╲` |
+| 19 | Pupil dilate | Random (15% / 4s, idle) | Eyes `o.o` → `@.@` |
+| 20 | Kneading | idle state | Paws alternate `/||  |\` ↔ `/|  ||\` |
+| 21 | Purr bubble | busy/thinking | 12 purr phrases rotate (purrr~/mrrrow~/nyaa~) |
+| 22 | Drag bristle | While dragging | Ears bristle `/╲╱╲` + shocked face `>.<` |
+
 ---
 
 ### 🖱️ Interactions (5)
@@ -157,7 +177,8 @@ opencode-mascot/
 │   │   └── sidebar-mascot.tsx       # Work page mascot (peek-a-boo)
 │   └── builtins/
 │       ├── yueer/                   # yueer (frames + effects)
-│       └── baozi/                   # baozi (frames + effects)
+│       ├── baozi/                   # baozi (frames + effects)
+│       └── cat/                     # cat (frames + effects)
 ```
 
 ## 🎨 Custom Characters
@@ -197,16 +218,16 @@ All built-in animations (blink/breath/walk/jump/sleep/drag/color-flash/bomb/fall
 
 | Category | Count |
 |----------|-------|
-| Built-in characters | 2 |
+| Built-in characters | 3 |
 | Expression frames | 5 / character |
-| Auto animations | 16 |
+| Auto animations | 22 |
 | Interactions | 5 |
 | Peek-a-boo behaviors | 3 |
 | Random events | 3 |
 | Alien text phrases | 24 (12/character) |
 | Flash colors | 8 |
 | Drag alien text | 6 |
-| **Total** | **33+** |
+| **Total** | **39+** |
 
 ## 📄 License
 

package/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "@mingxy/opencode-mascot",
-  "version": "0.5.9",
-  "description": "OpenCode TUI mascot plugin framework - customizable ASCII mascots for your terminal",
-  "author": "mingxy",
-  "license": "MIT",
-  "type": "module",
-  "main": "./tui.tsx",
-  "types": "./src/core/types.ts",
-  "exports": {
-    "./tui": "./tui.tsx",
-    "./types": "./src/core/types.ts"
-  },
-  "files": [
-    "tui.tsx",
-    "src/"
-  ],
-  "oc-plugin": [
-    "tui"
-  ],
-  "scripts": {
-    "typecheck": "tsc --noEmit"
-  },
-  "peerDependencies": {
-    "@opencode-ai/plugin": ">=0.1.0",
-    "@opentui/solid": ">=0.0.1"
-  },
-  "devDependencies": {
-    "@types/node": "^25.9.3",
-    "typescript": "^5.7.0"
-  },
-  "keywords": [
-    "opencode",
-    "tui",
-    "mascot",
-    "plugin",
-    "ascii-art"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/mengfanbo123/opencode-mascot"
-  }
-}
+{
+  "name": "@mingxy/opencode-mascot",
+  "version": "0.7.0",
+  "description": "OpenCode TUI mascot plugin framework - customizable ASCII mascots for your terminal",
+  "author": "mingxy",
+  "license": "MIT",
+  "type": "module",
+  "main": "./tui.tsx",
+  "types": "./src/core/types.ts",
+  "exports": {
+    "./tui": "./tui.tsx",
+    "./types": "./src/core/types.ts"
+  },
+  "files": [
+    "tui.tsx",
+    "src/"
+  ],
+  "oc-plugin": [
+    "tui"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=0.1.0",
+    "@opentui/solid": ">=0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "opencode",
+    "tui",
+    "mascot",
+    "plugin",
+    "ascii-art"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mengfanbo123/opencode-mascot"
+  }
+}

package/src/builtins/cat/frames.ts

@@ -0,0 +1,48 @@
+//     0123456789
+const defaultFrame = [
+  "  /\\_/\\   ",
+  " ( o.o )  ",
+  "  > ^ <   ",
+  " /|   |\\  ",
+  "(_|   |_) ",
+];
+
+const blinkFrame = [
+  "  /\\_/\\   ",
+  " ( -.- )  ",
+  "  > ^ <   ",
+  " /|   |\\  ",
+  "(_|   |_) ",
+];
+
+const happyFrame = [
+  "  /\\_/\\   ",
+  " ( ^ω^ )  ",
+  "  > ω <   ",
+  " /|   |\\  ",
+  "(_|   |_) ",
+];
+
+const thinkingFrame = [
+  "  /\\_/\\   ",
+  " ( o_o )  ",
+  "  > ? <   ",
+  " /|   |\\  ",
+  "(_|   |_) ",
+];
+
+const sleepingFrame = [
+  "  /\\_/\\   ",
+  " ( -.- )  ",
+  "  > z <   ",
+  " /|   |\\  ",
+  "(_|   |_) ",
+];
+
+export const frames = {
+  default: defaultFrame,
+  blink: blinkFrame,
+  happy: happyFrame,
+  thinking: thinkingFrame,
+  sleeping: sleepingFrame,
+};

package/src/builtins/cat/index.ts

@@ -0,0 +1,167 @@
+import type { MascotPack, EffectRenderCtx } from "../../core/types";
+import { frames } from "./frames";
+
+const PURR_TEXTS = [
+  "ᵖᵘʳʳʳ~", "ᵐʳʳᵒʷ~", "ᵐʷᵃᵃ~", "ⁿʸᵃᵃ~",
+  "ᵖᵘʳʳ..", "ᵐʸᵃ~..", "ᶠᵘʳʳ~", "ᵐⁱᵃᵒ~",
+  "ᶜʰᵘʳʳ..", "ᵉᵘⁿ~..", "ˢʰᵖᵘʳʳ~", "ⁿʸᵒ~",
+];
+const THINKING_FACES = ["o_o", "O_O", ">_o", "o_<", "⊙_⊙", "◑_◑"];
+
+const catEffects: MascotPack["effects"] = {
+  signals: [
+    { name: "tailAlt", initial: false },
+    { name: "earTwitch", initial: false },
+    { name: "pupilWide", initial: false },
+    { name: "kneadAlt", initial: false },
+    { name: "purrIdx", initial: 0 },
+    { name: "thinkingFaceIdx", initial: 0 },
+    { name: "thinkingCountdown", initial: 0 },
+  ],
+
+  timers: [
+    {
+      interval: 600,
+      update(ctx) {
+        ctx.set("tailAlt", !(ctx.get("tailAlt") as boolean));
+      },
+    },
+    {
+      interval: 2500,
+      update(ctx) {
+        if (Math.random() < 0.2) {
+          ctx.set("earTwitch", true);
+          setTimeout(() => ctx.set("earTwitch", false), 250);
+        }
+      },
+    },
+    {
+      interval: 4000,
+      update(ctx) {
+        if (ctx.state === "idle" && Math.random() < 0.15) {
+          ctx.set("pupilWide", true);
+          setTimeout(() => ctx.set("pupilWide", false), 1000);
+        }
+      },
+    },
+    {
+      interval: 400,
+      update(ctx) {
+        if (ctx.state === "idle") {
+          ctx.set("kneadAlt", !(ctx.get("kneadAlt") as boolean));
+        }
+      },
+    },
+    {
+      interval: 2000,
+      update(ctx) {
+        if (ctx.state === "busy" || ctx.state === "thinking") {
+          ctx.set("purrIdx", ((ctx.get("purrIdx") as number) + 1) % PURR_TEXTS.length);
+        }
+      },
+    },
+    {
+      interval: 1000,
+      update(ctx) {
+        if (ctx.state === "thinking" || ctx.state === "busy") {
+          let cd = ctx.get("thinkingCountdown") as number;
+          if (!cd || cd <= 0) cd = 5 + Math.floor(Math.random() * 11);
+          cd--;
+          if (cd <= 0) {
+            ctx.set("thinkingFaceIdx", ((ctx.get("thinkingFaceIdx") as number) + 1) % THINKING_FACES.length);
+          }
+          ctx.set("thinkingCountdown", cd);
+        } else {
+          ctx.set("thinkingFaceIdx", 0);
+          ctx.set("thinkingCountdown", 0);
+        }
+      },
+    },
+  ],
+
+  render(lines: string[], ctx: EffectRenderCtx): string[] {
+    const { state, breathPhase, dragging, get } = ctx;
+    let result = [...lines];
+
+    const tailAlt = get("tailAlt") as boolean;
+    const earTwitch = get("earTwitch") as boolean;
+    const pupilWide = get("pupilWide") as boolean;
+    const kneadAlt = get("kneadAlt") as boolean;
+
+    if (dragging) {
+      result[0] = "  /╲╱╲\\   ";
+      result[1] = " ( >.< )  ";
+      result[2] = "  > ! <   ";
+      result[3] = " /|   |\\  ";
+      result[4] = "(_|   |_) ";
+      return result;
+    }
+
+    if (!breathPhase) {
+      result = result.map((l) => l.replace(/\^/g, "'"));
+    }
+
+    if (earTwitch) {
+      result[0] = result[0].replace("/\\_/\\", "/╲_/\\");
+    }
+
+    if (tailAlt) {
+      result[4] = "(_|   |~) ";
+    } else {
+      result[4] = "(_|   |_) ";
+    }
+
+    if (pupilWide) {
+      const faceLine = result.findIndex((l) => /\(.*\)/.test(l));
+      if (faceLine >= 0) {
+        result[faceLine] = result[faceLine].replace("o.o", "@.@");
+      }
+    }
+
+    if (state === "idle") {
+      const armLine = result.findIndex((l) => l.includes("/|   |\\"));
+      if (armLine >= 0) {
+        result[armLine] = kneadAlt ? " /||  |\\  " : " /|  ||\\  ";
+      }
+    }
+
+    if (state === "thinking" || state === "busy") {
+      const faceIdx = get("thinkingFaceIdx") as number;
+      const faceLine = result.findIndex((l) => /\(.*\)/.test(l));
+      if (faceLine >= 0) {
+        result[faceLine] = result[faceLine].replace(/\(.*?\)/, `( ${THINKING_FACES[faceIdx]} )`);
+      }
+    }
+
+    if (state === "busy" || state === "thinking") {
+      const idx = get("purrIdx") as number;
+      const earLine = 0;
+      result[earLine] = result[earLine].trimEnd() + " " + PURR_TEXTS[idx];
+    }
+
+    return result;
+  },
+};
+
+export const catPack: MascotPack = {
+  name: "@mingxy/mascot-cat",
+  displayName: "小猫",
+  version: "0.1.0",
+  author: "mingxy",
+  description: "Orange tabby cat — purring, kneading, and knocking things off your terminal.",
+
+  frames,
+
+  colors: {
+    defaultFg: "#FFA500",
+  },
+
+  animations: {
+    blinkInterval: 2500,
+    blinkChance: 0.3,
+    expressionInterval: 8000,
+    idleTimeout: 90000,
+  },
+
+  effects: catEffects,
+};

package/src/builtins/props/box.ts

@@ -0,0 +1,69 @@
+import type { PropPack } from "../../core/types";
+
+/**
+ * 立体箱子道具 — idle 常驻容器
+ *
+ * 尺寸: 14 宽 × 8 高（等轴测视角，正面+顶面+侧面深度）
+ * 动画: 4 帧循环
+ *   1: 关闭（盖子盖上，正面 ᵇᵒˣ 火星文）
+ *   2: 微动（盖子抖动 + 内部物品晃动）
+ *   3: 打开（盖子翻开，露出月儿剪影）
+ *   4: 月儿冒头（月儿从箱子里探出）
+ * 正面 ᵇᵒˣ 火星文标识，里面是月儿剪影（呆毛☆+圆脸+迷你身体）
+ */
+
+const frames: string[][] = [
+  // 帧1: 关闭
+  [
+    "   ╭──────╮   ",
+    "  ╱░░░░░░░╲   ",
+    " ╱────────╲   ",
+    "│░ᵇᵒˣ░░░░░│   ",
+    "│░░░░░░░░░│   ",
+    "│░░░░░░░░░│   ",
+    "╰──────────╯─┐",
+    "            ╲ ",
+  ],
+  // 帧2: 微动
+  [
+    "   ╭~~~~~~╮   ",
+    "  ╱▒░░░▒░░╲   ",
+    " ╱~~────~~╲   ",
+    "│░ᵇᵒˣ░▒░░░│   ",
+    "│░░▓▓░░░░░│   ",
+    "│░░░░░░░░░│   ",
+    "╰──────────╯─┐",
+    "            ╲ ",
+  ],
+  // 帧3: 打开（露出月儿剪影）
+  [
+    "   ╭~~~~~~╮   ",
+    "  ╱  ☆    ╲   ",
+    " ╱~~────~~╲   ",
+    "│░(^-^)░░░│   ",
+    "│░┃█┃░░░░░│   ",
+    "│░░░░░░░░░│   ",
+    "╰──────────╯─┐",
+    "            ╲ ",
+  ],
+  // 帧4: 月儿冒头
+  [
+    "   ╭~~~~~~╮   ",
+    "  ╱  ☆    ╲   ",
+    " ╱(^-^)───╲   ",
+    "│░┃█┃░░░░░│   ",
+    "│░░░░░░░░░│   ",
+    "│░░░░░░░░░│   ",
+    "╰──────────╯─┐",
+    "            ╲ ",
+  ],
+];
+
+export const boxProp: PropPack = {
+  name: "box",
+  frames,
+  frameInterval: 1500,
+  trigger: "idle",
+  position: "side-left",
+  weight: 1,
+};

package/src/builtins/props/laptop.ts

@@ -0,0 +1,53 @@
+import type { PropPack } from "../../core/types";
+
+/**
+ * 显示器道具 — busy 状态主力道具
+ *
+ * 尺寸: 16 宽 × 4 高
+ * 结构: 屏幕框(┌┐) + 2行内容(提示符+状态) + 底座连接(||) + 底座(▓)
+ * 动画: 8 帧屏幕状态轮播
+ *   1-2: 光标闪（>_ ↔ > ）
+ *   3: thinking
+ *   4: writing
+ *   5: git push
+ *   6: bug!
+ *   7: npm install
+ *   8: done ✓
+ * $ 保留，opencode 火星文，无空格
+ */
+
+const W = 14; // 屏幕内容区宽
+
+const TOP = "┌" + "─".repeat(W) + "┐";
+const BOT = "└" + "─".repeat(6) + "||" + "─".repeat(6) + "┘";
+const BASE = "▓".repeat(16);
+
+const ln = (s: string) => "│" + s.padEnd(W) + "│";
+
+const states = [
+  ">_",
+  "> ",
+  ">ᵗʰⁿᵏⁱⁿᵍ...",
+  ">ʷʳⁱᵗⁱⁿᵍ...",
+  ">ᵍⁱᵗᵖᵘˢʰ...",
+  ">ᵇᵘᵍ!ᵇᵘᵍ!",
+  ">ⁿᵖᵐⁱⁿˢᵗᵃˡˡ",
+  ">ᵈᵒⁿᵉ✓",
+];
+
+const frames: string[][] = states.map((st) => [
+  TOP,
+  ln("~$ᵒᵖᵉⁿᶜᵒᵈᵉ"),
+  ln(st),
+  BOT,
+  BASE,
+]);
+
+export const laptopProp: PropPack = {
+  name: "laptop",
+  frames,
+  frameInterval: 800,
+  trigger: "busy",
+  position: "side-right",
+  weight: 0.7,
+};

package/src/builtins/props/pad.ts

@@ -0,0 +1,65 @@
+import type { PropPack } from "../../core/types";
+
+/**
+ * Pad 道具 — busy 状态变体道具
+ *
+ * 尺寸: 18 宽 × 9 高（双层框+.•摄像头+底部◉Home键）
+ * 屏幕区: 12 宽 × 4 高
+ * 叙事: 月儿小人玩游戏，又菜又爱玩
+ *   贪吃蛇 6帧: 开局→走→撞墙→哭→不服→重开
+ *   俄罗斯方块 4帧: 开局→堆积→满→over
+ *   2048 4帧: 开局→合并→128→over
+ *   切换 1帧: next!
+ * 月儿小人: ☆ 呆毛 + (^-^) 圆脸 + ┃█┃ 身体（迷你版）
+ */
+
+const W = 12; // 屏幕内容区宽
+
+const OUTER_TOP = "╭.•" + "─".repeat(14) + "╮";
+const INNER_TOP = "│ ┌" + "─".repeat(W) + "┐ │";
+const INNER_BOT = "│ └" + "─".repeat(W) + "┘ │";
+const DOT_ROW = "│ " + " ".repeat(6) + "◉" + " ".repeat(7) + " │";
+const OUTER_BOT = "╰" + "─".repeat(16) + "╯";
+
+const scr = (rows: string[]) =>
+  rows.map((r) => "│ │" + r.padEnd(W) + "│ │");
+
+const games: string[][] = [
+  // 贪吃蛇 6帧
+  ["  ☆  ᵇᵉᵍⁱⁿ ", "(^-^) ◯→  ●", " ┃█┃  ˢ:0  ", "           "],
+  ["  ☆       ", "(^-^) ◯◯→ ●", " ┃█┃  ˢ:1  ", "           "],
+  ["  ☆       ", "(×_×) ◯◯💥 ", " ┃█┃  ᵍᵍ!  ", "           "],
+  ["  ☆       ", "(╥_╥) ᵒᵛᵉʳ ", " ┃█┃  ˢ:1  ", "           "],
+  ["  ☆       ", "(¬_¬) ᵃᵍᵃⁱⁿ", " ┃█┃       ", "           "],
+  ["  ☆  ᵍᵒ!  ", "(^-^) ◯→  ●", " ┃█┃  ˢ:0  ", "           "],
+  // 俄罗斯方块 4帧
+  ["  ☆  ᵇᵉᵍⁱⁿ ", "(^-^)  ▣   ", " ┃█┃       ", "           "],
+  ["  ☆       ", "(^-^) ▣▣   ", " ┃█┃ ▣▣▣▣  ", "           "],
+  ["  ☆       ", "(×_×)      ", " ┃█┃ ▣▣▣▣▣▣", "  ᶠᵘˡˡ!    "],
+  ["  ☆       ", "(╥_╥) ᵒᵛᵉʳ ", " ┃█┃       ", "           "],
+  // 2048 4帧
+  ["  ☆  ᵇᵉᵍⁱⁿ ", "(^-^) [ 2 ]", " ┃█┃       ", "           "],
+  ["  ☆       ", "(^-^) [ 4 ]", " ┃█┃  ᵒᵒⁿ  ", "           "],
+  ["  ☆       ", "(⊙_⊙) [128]", " ┃█┃  ʷᵒʷ  ", "           "],
+  ["  ☆       ", "(╥_╥) ᵒᵛᵉʳ ", " ┃█┃       ", "           "],
+  // 切换
+  ["  ☆       ", "(^-^) ⁿᵉˣᵗ!", " ┃█┃       ", "           "],
+];
+
+const frames: string[][] = games.map((rows) => [
+  OUTER_TOP,
+  INNER_TOP,
+  ...scr(rows),
+  INNER_BOT,
+  DOT_ROW,
+  OUTER_BOT,
+]);
+
+export const padProp: PropPack = {
+  name: "pad",
+  frames,
+  frameInterval: 700,
+  trigger: "busy",
+  position: "front",
+  weight: 0.3,
+};

package/src/components/sidebar-mascot.tsx

@@ -5,6 +5,7 @@ import type { JSX } from "@opentui/solid";
 import type { MascotPack, MascotState } from "../core/types";
 import { createAnimatedRenderer } from "../core/ascii-renderer";
 import { onCelebrate, onVersion, onScatter } from "../core/celebration-bus";
+import { pickPropByTrigger, getProp } from "../core/prop-loader";
 
 interface SidebarMascotProps {
   mascots: Record<string, MascotPack>;
@@ -42,6 +43,7 @@ export function SidebarMascot(props: SidebarMascotProps): JSX.Element {
       : names[0];
 
   const [currentName, setCurrentName] = createSignal(initialName);
+  const [userOverride, setUserOverride] = createSignal(false);
   const [posX, setPosX] = createSignal(20);
   const [posY, setPosY] = createSignal(2);
   const [containerWidth, setContainerWidth] = createSignal(0);
@@ -74,6 +76,7 @@ export function SidebarMascot(props: SidebarMascotProps): JSX.Element {
     const cur = currentName();
     const idx = names.indexOf(cur);
     setCurrentName(names[(idx + 1) % names.length]);
+    setUserOverride(true);
   };
 
   const getCw = () => containerWidth() || 30;
@@ -142,6 +145,7 @@ export function SidebarMascot(props: SidebarMascotProps): JSX.Element {
   const setStateWithSwitch = (s: MascotState) => {
     const cur = currentName();
     renderers[cur].setState(s);
+    if (userOverride()) return;
     const target = DEFAULT_STATE_MAP[s];
     if (target && target !== cur && props.mascots[target]) {
       setCurrentName(target);
@@ -155,8 +159,20 @@ export function SidebarMascot(props: SidebarMascotProps): JSX.Element {
     if (statusType === "busy" || statusType === "retry") {
       if (hideSide) returnToView();
       renderers[currentName()].setState("busy");
+      // 先显示箱子"打开"动画300ms，再切换到 busy 道具（道具从箱子里掉出来）
+      const busyProp = pickPropByTrigger("busy");
+      if (busyProp) {
+        renderers[currentName()].setProp(getProp("box") ?? null);
+        setTimeout(() => {
+          renderers[currentName()].setProp(busyProp);
+        }, 300);
+      } else {
+        renderers[currentName()].setProp(getProp("box") ?? null);
+      }
     } else {
       setStateWithSwitch("idle");
+      // idle 时显示箱子常驻
+      renderers[currentName()].setProp(getProp("box") ?? null);
     }
   });
 
@@ -169,7 +185,10 @@ export function SidebarMascot(props: SidebarMascotProps): JSX.Element {
     const target = data as { name?: string } | null;
     if (target?.name) {
       const name = target.name;
-      if (props.mascots[name] && name !== currentName()) setCurrentName(name);
+      if (props.mascots[name] && name !== currentName()) {
+        setCurrentName(name);
+        setUserOverride(true);
+      }
     } else {
       switchToNext();
     }
@@ -205,6 +224,13 @@ export function SidebarMascot(props: SidebarMascotProps): JSX.Element {
     renderers[currentName()].scatterIn();
   }, 2000);
 
+  // 启动后显示箱子（在 scatter 之后）
+  setTimeout(() => {
+    if (!renderers[currentName()].getProp()) {
+      renderers[currentName()].setProp(getProp("box") ?? null);
+    }
+  }, 2500);
+
   return (
     <box
       position="absolute"

package/src/core/ascii-renderer.tsx

@@ -2,7 +2,7 @@
 
 import { createSignal, onCleanup } from "solid-js";
 import type { JSX } from "@opentui/solid";
-import type { MascotPack, MascotState, EffectTimerCtx, EffectRenderCtx } from "./types";
+import type { MascotPack, MascotState, EffectTimerCtx, EffectRenderCtx, PropPack, PropPosition } from "./types";
 
 const SUPERSCRIPT: Record<string, string> = {
   "0": "⁰", "1": "¹", "2": "²", "3": "³", "4": "⁴",
@@ -55,6 +55,8 @@ export function createAnimatedRenderer(pack: MascotPack): {
   showVersion: (version: string) => void;
   scatterIn: () => void;
   explode: () => void;
+  setProp: (prop: PropPack | null) => void;
+  getProp: () => PropPack | null;
 } {
   const anim = { ...DEFAULT_ANIM, ...pack.animations };
   const fg = pack.colors?.defaultFg || undefined;
@@ -74,7 +76,11 @@ export function createAnimatedRenderer(pack: MascotPack): {
   const [zzz, setZzz] = createSignal<string | null>(null);
   const [bomb, setBomb] = createSignal<{ fuse: string; count: string } | null>(null);
   const [scatter, setScatter] = createSignal<{ dx: number; dy: number }[] | null>(null);
+  const [activeProp, setActiveProp] = createSignal<PropPack | null>(null);
+  const [propFrameIdx, setPropFrameIdx] = createSignal(0);
+  const [propPosition, setPropPosition] = createSignal<PropPosition | null>(null);
 
+  let propTimer: ReturnType<typeof setInterval> | null = null;
   let flashTimer: ReturnType<typeof setInterval> | null = null;
   let dragMsgTimer: ReturnType<typeof setInterval> | null = null;
   let zzzTimer: ReturnType<typeof setInterval> | null = null;
@@ -118,6 +124,9 @@ export function createAnimatedRenderer(pack: MascotPack): {
     if (explodeTimer) { clearTimeout(explodeTimer); explodeTimer = null; }
     setBomb(null);
   };
+  const stopPropTimer = () => {
+    if (propTimer) { clearInterval(propTimer); propTimer = null; }
+  };
 
   const stopAllAnimations = () => {
     stopFlash();
@@ -302,6 +311,7 @@ export function createAnimatedRenderer(pack: MascotPack): {
     stopFall();
     stopBomb();
     if (zzzTimer) { clearInterval(zzzTimer); zzzTimer = null; }
+    stopPropTimer();
   });
 
   // ─── Render ───
@@ -319,6 +329,9 @@ export function createAnimatedRenderer(pack: MascotPack): {
     scatter();
     bomb();
     versionMsg();
+    activeProp();
+    propFrameIdx();
+    propPosition();
 
     for (const [, [get]] of extraSignals) {
       get();
@@ -351,6 +364,47 @@ export function createAnimatedRenderer(pack: MascotPack): {
       lines = effects.render(lines, renderCtx);
     }
 
+    // ─── Prop overlay ───
+    const prop = activeProp();
+    if (prop) {
+      const propFramesRaw = Array.isArray(prop.frames[0])
+        ? (prop.frames as string[][])
+        : [prop.frames as string[]];
+      const propLines = propFramesRaw[propFrameIdx() % propFramesRaw.length] ?? propFramesRaw[0];
+
+      if (propLines.length > 0) {
+        const pos = propPosition();
+        if (pos === 'front') {
+          const overlayCount = Math.min(propLines.length, lines.length);
+          const startRow = Math.floor((lines.length - overlayCount) / 2);
+          for (let i = 0; i < overlayCount; i++) {
+            lines[startRow + i] = propLines[i];
+          }
+        } else {
+          const charWidth = lines[0]?.length ?? 0;
+          const propWidth = propLines[0]?.length ?? 0;
+          const charHeight = lines.length;
+          const propHeight = propLines.length;
+          const maxLines = Math.max(charHeight, propHeight);
+          const charPad = Math.floor((maxLines - charHeight) / 2);
+          const propPad = Math.floor((maxLines - propHeight) / 2);
+          const sep = "  ";
+
+          const merged: string[] = [];
+          for (let i = 0; i < maxLines; i++) {
+            const cLine = (i >= charPad && i < charPad + charHeight)
+              ? lines[i - charPad]
+              : " ".repeat(charWidth);
+            const pLine = (i >= propPad && i < propPad + propHeight)
+              ? propLines[i - propPad]
+              : " ".repeat(propWidth);
+            merged.push(pos === 'side-right' ? cLine + sep + pLine : pLine + sep + cLine);
+          }
+          lines = merged;
+        }
+      }
+    }
+
     const top = jumpOffset();
     const left = offset > 0 ? offset : 0;
     const cel = celebrate();
@@ -505,7 +559,7 @@ export function createAnimatedRenderer(pack: MascotPack): {
   const showVersion = (version: string) => {
     stopVersion();
     setVersionMsg(`ᵛ${toSuperscript(version)}`);
-    versionTimer = setTimeout(() => { setVersionMsg(null); versionTimer = null; }, 3000);
+    versionTimer = setTimeout(() => { setVersionMsg(null); versionTimer = null; }, 5000);
   };
 
   const scatterIn = () => {
@@ -574,5 +628,27 @@ export function createAnimatedRenderer(pack: MascotPack): {
     }, 700);
   };
 
-  return { element, getState: currentState, setState, toggleWalk, setDragging, celebrateUpdate, bounce, showVersion, scatterIn, explode };
+  const setProp = (prop: PropPack | null) => {
+    setActiveProp(prop);
+    setPropFrameIdx(0);
+    if (prop) {
+      const pos: PropPosition = prop.position === 'random'
+        ? (Math.random() < 0.5 ? 'side-left' : 'side-right')
+        : prop.position;
+      setPropPosition(pos);
+      stopPropTimer();
+      if (Array.isArray(prop.frames[0]) && prop.frameInterval) {
+        propTimer = setInterval(() => {
+          setPropFrameIdx((idx) => (idx + 1) % (prop.frames as string[][]).length);
+        }, prop.frameInterval);
+      }
+    } else {
+      setPropPosition(null);
+      stopPropTimer();
+    }
+  };
+
+  const getProp = () => activeProp();
+
+  return { element, getState: currentState, setState, toggleWalk, setDragging, celebrateUpdate, bounce, showVersion, scatterIn, explode, setProp, getProp };
 }

package/src/core/mascot-loader.ts

@@ -1,10 +1,12 @@
 import type { MascotPack } from "./types"
 import { yueerPack } from "../builtins/yueer"
 import { baoziPack } from "../builtins/baozi"
+import { catPack } from "../builtins/cat"
 
 const BUILTINS: Record<string, MascotPack> = {
   yueer: yueerPack,
   baozi: baoziPack,
+  cat: catPack,
 }
 
 const ALL_NAMES = Object.keys(BUILTINS)

package/src/core/prop-loader.ts

@@ -0,0 +1,38 @@
+import type { PropPack, PropTrigger } from "./types";
+import { laptopProp } from "../builtins/props/laptop";
+import { padProp } from "../builtins/props/pad";
+import { boxProp } from "../builtins/props/box";
+
+// 内置道具注册表
+const BUILTIN_PROPS: Record<string, PropPack> = {
+  laptop: laptopProp,
+  pad: padProp,
+  box: boxProp,
+};
+
+const loaded: Record<string, PropPack> = { ...BUILTIN_PROPS };
+
+export function registerProp(prop: PropPack): void {
+  loaded[prop.name] = prop;
+}
+
+export function getProp(name: string): PropPack | undefined {
+  return loaded[name];
+}
+
+export function getAllProps(): Record<string, PropPack> {
+  return loaded;
+}
+
+/** 按 trigger 筛选道具，按 weight 加权随机选一个 */
+export function pickPropByTrigger(trigger: PropTrigger): PropPack | null {
+  const candidates = Object.values(loaded).filter((p) => p.trigger === trigger);
+  if (candidates.length === 0) return null;
+  const totalWeight = candidates.reduce((sum, p) => sum + (p.weight ?? 1), 0);
+  let r = Math.random() * totalWeight;
+  for (const p of candidates) {
+    r -= p.weight ?? 1;
+    if (r <= 0) return p;
+  }
+  return candidates[candidates.length - 1];
+}

package/src/core/types.ts

@@ -126,3 +126,26 @@ export interface MascotPack {
   /** Mascot-specific animation effects (timers + render) */
   effects?: MascotEffects;
 }
+
+// ─── Prop system types ───
+
+/** 道具触发条件 */
+export type PropTrigger = 'busy' | 'idle' | 'startup' | 'random';
+
+/** 道具渲染位置 */
+export type PropPosition = 'side-left' | 'side-right' | 'front' | 'random';
+
+/** 道具包定义 */
+export interface PropPack {
+  name: string;
+  /** 静态帧（string[]）或多帧动画（string[][]），每行必须等宽 */
+  frames: string[] | string[][];
+  /** 多帧动画时的帧切换间隔ms，默认 800 */
+  frameInterval?: number;
+  /** 触发条件 */
+  trigger: PropTrigger;
+  /** 默认渲染位置 */
+  position: PropPosition;
+  /** 同trigger多个道具时按权重随机挑选，默认 1 */
+  weight?: number;
+}

package/tui.tsx

@@ -36,6 +36,7 @@ const tui: TuiPlugin = async (api, _options) => {
 
   checkAndUpdate(pluginVersion, (newVersion) => {
     emitCelebrate(newVersion);
+    emitVersion(newVersion);
   }).catch(() => {});
 
   setTimeout(() => emitScatter(), 100);