@mingxy/opencode-mascot 0.1.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mingxy/opencode-mascot",
+  "version": "0.1.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": {
+    "@opentui/solid": ">=0.0.1",
+    "@opencode-ai/plugin": ">=0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "keywords": ["opencode", "tui", "mascot", "plugin", "ascii-art"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mingxy/opencode-mascot"
+  }
+}

package/src/builtins/yueer/colors.ts

@@ -0,0 +1,34 @@
+/**
+ * 月儿 (Yue'er) — Color zone definitions.
+ *
+ * Zones are matched by the ASCII characters in frame lines.
+ * Each zone maps to a foreground (fg) and optional background (bg) color.
+ */
+
+export const colors = {
+  zones: {
+    /** Long flowing hair — silver white */
+    hair: {
+      fg: "#E8E0F0",
+    },
+    /** Imperial crown / headdress — gold */
+    crown: {
+      fg: "#FFD700",
+    },
+    /** Big anime eyes — ice blue */
+    eyes: {
+      fg: "#66CCFF",
+    },
+    /** Face and skin — warm peach */
+    skin: {
+      fg: "#FFE0BD",
+    },
+    /** Elegant robe / dress — ice blue */
+    dress: {
+      fg: "#7CB9E8",
+    },
+  },
+
+  /** Default foreground for unmatched characters — cool silver */
+  defaultFg: "#B8C4D8",
+};

package/src/builtins/yueer/frames.ts

@@ -0,0 +1,99 @@
+/**
+ * 月儿 (Yue'er) — ASCII art frames for the Ice Empress mascot.
+ *
+ * Each expression is a single frame (string[]) where every string is one line.
+ * ALL frames have the same line count (14) for consistent rendering.
+ *
+ * Key design elements:
+ *  - Imperial crown with three prongs
+ *  - Long flowing silver-white hair
+ *  - Big anime eyes (ice blue)
+ *  - Elegant ice-blue robe with fur trim
+ */
+
+export const frames = {
+  default: [
+    "       _.+._       ",
+    "     .*       *.   ",
+    "   .*           *. ",
+    "  *    {crown}    *",
+    "  |  /*=====*\\  | ",
+    "  | |  O   O  | | ",
+    "  | |   \\_/   | | ",
+    "  |  \\  ___  /  | ",
+    "  |   \\_____/   | ",
+    "  |*~~*~~~~~*~~*| ",
+    "   *~~*      ~~*  ",
+    "    |*        *|   ",
+    "    |*        *|   ",
+    "    *==========*   ",
+  ],
+
+  blink: [
+    "       _.+._       ",
+    "     .*       *.   ",
+    "   .*           *. ",
+    "  *    {crown}    *",
+    "  |  /*=====*\\  | ",
+    "  | |  -   -  | | ",
+    "  | |   \\_/   | | ",
+    "  |  \\  ___  /  | ",
+    "  |   \\_____/   | ",
+    "  |*~~*~~~~~*~~*| ",
+    "   *~~*      ~~*  ",
+    "    |*        *|   ",
+    "    |*        *|   ",
+    "    *==========*   ",
+  ],
+
+  happy: [
+    "       _.+._       ",
+    "     .*       *.   ",
+    "   .*           *. ",
+    "  *    {crown}    *",
+    "  |  /*=====*\\  | ",
+    "  | |  ^   ^  | | ",
+    "  | |   \\_/   | | ",
+    "  |  \\  ___  /  | ",
+    "  |   \\_____/   | ",
+    "  |*~~*~~~~~*~~*| ",
+    "   *~~*      ~~*  ",
+    "    |*        *|   ",
+    "    |*        *|   ",
+    "    *==========*   ",
+  ],
+
+  thinking: [
+    "       _.+._       ",
+    "     .*       *.   ",
+    "   .*           *. ",
+    "  *    {crown}    *",
+    "  |  /*=====*\\  | ",
+    "  | |  O   -  | | ",
+    "  | |    <    | | ",
+    "  |  \\  ___  /  | ",
+    "  |   \\_____/   | ",
+    "  |*~~*~~~~~*~~*| ",
+    "   *~~*      ~~*  ",
+    "    |*        *|   ",
+    "    |*        *|   ",
+    "    *==========*   ",
+  ],
+
+  sleeping: [
+    "       _.+._       ",
+    "     .*       *.   ",
+    "   .*           *. ",
+    "  *    {crown}    *",
+    "  |  /*=====*\\  | ",
+    "  | |  .   .  | | ",
+    "  | |   ---   | | ",
+    "  |  \\  ___  /  | ",
+    "  |   \\_____/   | ",
+    "  |*~~*~~~~~*~~*| ",
+    "   *~~*      ~~*  ",
+    "    |*        *|   ",
+    "    |*        *|   ",
+    "    *==========*   ",
+  ],
+};

package/src/builtins/yueer/index.ts

@@ -0,0 +1,41 @@
+/**
+ * 月儿 (Yue'er) — Ice Empress mascot pack.
+ *
+ * Nine Heavens' Empress with silver-white hair, ice-blue eyes, and imperial crown.
+ * She awaits her Master's command with grace and quiet devotion.
+ */
+
+import type { MascotPack } from "../../core/types";
+import { frames } from "./frames";
+import { colors } from "./colors";
+
+export const yueerPack: MascotPack = {
+  name: "@mingxy/mascot-yueer",
+  displayName: "月儿",
+  version: "0.1.0",
+  author: "mingxy",
+  description:
+    "Ice Empress of the Nine Heavens — elegant, powerful, and devoted to her Master.",
+
+  frames,
+  colors,
+
+  animations: {
+    blinkInterval: 2500,
+    blinkChance: 0.3,
+    expressionInterval: 50000,
+    idleTimeout: 90000,
+  },
+
+  sidebar: {
+    greetings: [
+      "师尊，月儿在此候命~",
+      "月儿恭候师尊多时了~",
+      "师尊今日气色不错呢~",
+    ],
+    busyPhrases: [
+      "月儿正在铸造法器...",
+      "驱除心魔中...",
+    ],
+  },
+};

package/src/components/sidebar-mascot.tsx

@@ -0,0 +1,41 @@
+/** @jsxImportSource @opentui/solid */
+
+import { createSignal, createEffect } from "solid-js";
+import type { JSX } from "@opentui/solid";
+import type { MascotPack, MascotState } from "../core/types";
+import { createAnimatedRenderer } from "../core/ascii-renderer";
+
+interface SidebarMascotProps {
+  mascot: MascotPack;
+  isRunning?: boolean;
+}
+
+export function SidebarMascot(props: SidebarMascotProps): JSX.Element {
+  const { element, setState } = createAnimatedRenderer(props.mascot);
+
+  const greetings = props.mascot.sidebar?.greetings ?? ["~"];
+  const busyPhrases = props.mascot.sidebar?.busyPhrases ?? ["Working..."];
+
+  const initialGreeting = greetings[Math.floor(Math.random() * greetings.length)];
+  const [stateText, setStateText] = createSignal<string>(initialGreeting);
+
+  createEffect(() => {
+    if (props.isRunning) {
+      setState("busy" as MascotState);
+      const phrase = busyPhrases[Math.floor(Math.random() * busyPhrases.length)];
+      setStateText(phrase);
+    } else {
+      setState("idle");
+      setStateText(greetings[Math.floor(Math.random() * greetings.length)]);
+    }
+  });
+
+  return (
+    <box flexDirection="column" paddingTop={1} paddingBottom={1} paddingLeft={1}>
+      {element()}
+      <text fg="gray" wrapMode="word">
+        {stateText()}
+      </text>
+    </box>
+  );
+}

package/src/core/ascii-renderer.tsx

@@ -0,0 +1,79 @@
+/** @jsxImportSource @opentui/solid */
+
+import { createSignal, onCleanup } from "solid-js";
+import type { JSX } from "@opentui/solid";
+import type { MascotPack, MascotState } from "./types";
+
+const STATE_TO_FRAME: Record<MascotState, string> = {
+  idle: "default",
+  busy: "default",
+  happy: "happy",
+  thinking: "thinking",
+  sleeping: "sleeping",
+};
+
+const DEFAULT_ANIM = {
+  blinkInterval: 2000,
+  blinkChance: 0.35,
+  expressionInterval: 45000,
+  idleTimeout: 120000,
+};
+
+function getFrame(pack: MascotPack, frameName: string): string[] {
+  const frames = pack.frames as Record<string, string[] | undefined>;
+  return frames[frameName] ?? frames["default"] ?? [];
+}
+
+export function renderFrame(pack: MascotPack, state: MascotState): JSX.Element {
+  const frameName = STATE_TO_FRAME[state] ?? "default";
+  const lines = getFrame(pack, frameName);
+  const fg = pack.colors.defaultFg || undefined;
+
+  return (
+    <box flexDirection="column">
+      {lines.map((line: string) => (
+        <text fg={fg}>{line}</text>
+      ))}
+    </box>
+  );
+}
+
+export function createAnimatedRenderer(pack: MascotPack): {
+  element: () => JSX.Element;
+  setState: (s: MascotState) => void;
+} {
+  const anim = { ...DEFAULT_ANIM, ...pack.animations };
+  const [currentState, setCurrentState] = createSignal<MascotState>("idle");
+  const [frameOverride, setFrameOverride] = createSignal<string | null>(null);
+
+  const blinkTimer = setInterval(() => {
+    if (Math.random() < anim.blinkChance) {
+      setFrameOverride("blink");
+      setTimeout(() => setFrameOverride(null), 150);
+    }
+  }, anim.blinkInterval);
+
+  const availableFrames = Object.keys(pack.frames).filter(
+    (k) => k !== "default" && k !== "blink"
+  );
+  const expressionTimer = setInterval(() => {
+    if (currentState() === "idle" && availableFrames.length > 0) {
+      const pick = availableFrames[Math.floor(Math.random() * availableFrames.length)];
+      setFrameOverride(pick);
+      setTimeout(() => setFrameOverride(null), 2000);
+    }
+  }, anim.expressionInterval);
+
+  onCleanup(() => {
+    clearInterval(blinkTimer);
+    clearInterval(expressionTimer);
+  });
+
+  const element = () => {
+    const override = frameOverride();
+    const state = override ? (override as MascotState) : currentState();
+    return renderFrame(pack, state);
+  };
+
+  return { element, setState: setCurrentState };
+}

package/src/core/mascot-loader.ts

@@ -0,0 +1,18 @@
+import type { MascotPack } from "./types"
+import { yueerPack } from "../builtins/yueer"
+
+const BUILTINS: Record<string, MascotPack> = {
+  yueer: yueerPack,
+}
+
+export async function loadMascot(options?: Record<string, unknown>): Promise<MascotPack> {
+  const mascotName = (options?.mascot as string) || "yueer"
+  
+  if (BUILTINS[mascotName]) {
+    return BUILTINS[mascotName]
+  }
+  
+  // Future: npm package loading, local file loading
+  // Fallback to yueer
+  return yueerPack
+}

package/src/core/types.ts

@@ -0,0 +1,141 @@
+/**
+ * Expression frame names available for a mascot.
+ * All are optional except "default".
+ */
+export type ExpressionName = 'default' | 'blink' | 'happy' | 'thinking' | 'busy' | 'sleeping';
+
+/**
+ * Current state of the mascot, determines which expression is shown.
+ */
+export type MascotState = 'idle' | 'busy' | 'thinking' | 'sleeping' | 'happy';
+
+/**
+ * Color definition for a zone within a frame.
+ */
+export interface ZoneColor {
+  /** ANSI foreground color code or CSS color */
+  fg?: string;
+  /** ANSI background color code or CSS color */
+  bg?: string;
+}
+
+/**
+ * Animation timing configuration with sensible defaults.
+ */
+export interface AnimationConfig {
+  /** Milliseconds between blink checks (default: 2000) */
+  blinkInterval?: number;
+  /** Probability of a blink on each check, 0–1 (default: 0.35) */
+  blinkChance?: number;
+  /** Milliseconds between random expression changes (default: 45000) */
+  expressionInterval?: number;
+  /** Milliseconds of inactivity before entering sleep state (default: 120000) */
+  idleTimeout?: number;
+}
+
+/**
+ * Sidebar display configuration.
+ */
+export interface SidebarConfig {
+  /** Rotating greeting messages shown below the mascot */
+  greetings?: string[];
+  /** Rotating phrases shown while in busy state */
+  busyPhrases?: string[];
+  /** Sidebar width in characters (default: mascot frame width) */
+  width?: number;
+}
+
+/**
+ * Context passed to render hooks.
+ */
+export interface RenderContext {
+  /** Current mascot state */
+  state: MascotState;
+  /** Current frame index within the active expression */
+  frameIndex: number;
+  /** Unix timestamp (ms) of this render call */
+  timestamp: number;
+  /** Optional session metadata from the host */
+  sessionData?: {
+    tokenUsage?: number;
+    tokenLimit?: number;
+    model?: string;
+  };
+}
+
+/**
+ * Lifecycle hooks for customizing mascot behavior.
+ */
+export interface MascotHooks {
+  /** Called before each frame render. Return modified frame lines or the original. */
+  beforeRender?: (context: RenderContext, frame: string[]) => string[];
+  /** Called when the mascot state transitions. */
+  onStateChange?: (prevState: MascotState, newState: MascotState) => void;
+}
+
+/**
+ * A complete mascot pack definition.
+ *
+ * Each pack provides ASCII-art frames for different expressions,
+ * color zones, animation timing, sidebar text, and optional hooks.
+ */
+export interface MascotPack {
+  /** Unique machine-readable identifier (e.g. "tuxie") */
+  name: string;
+  /** Human-readable display name (e.g. "Tuxie the Penguin") */
+  displayName: string;
+  /** Semantic version string (e.g. "1.0.0") */
+  version: string;
+  /** Pack author or team */
+  author: string;
+  /** Short description of the mascot */
+  description: string;
+
+  /**
+   * Expression frames: expression name → array of ASCII-art lines.
+   * Each entry is a single frame (one multi-line drawing).
+   * "default" is required; all other expressions are optional.
+   */
+  frames: {
+    default: string[];
+    blink?: string[];
+    happy?: string[];
+    thinking?: string[];
+    busy?: string[];
+    sleeping?: string[];
+  };
+
+  /**
+   * Color mapping for the mascot frames.
+   * Zones are matched by substring or named markers in the frame lines.
+   */
+  colors: {
+    /** Named zone → foreground/background color */
+    zones?: Record<string, ZoneColor>;
+    /** Default foreground applied to unmatched characters */
+    defaultFg?: string;
+    /** Default background applied to unmatched characters */
+    defaultBg?: string;
+  };
+
+  /** Animation timing overrides */
+  animations?: AnimationConfig;
+
+  /** Sidebar content configuration */
+  sidebar?: SidebarConfig;
+
+  /** Optional lifecycle hooks */
+  hooks?: MascotHooks;
+}
+
+/**
+ * User-facing configuration merged from opencode config file.
+ */
+export interface MascotConfig {
+  /** Name of the selected mascot pack */
+  mascot: string;
+  /** Enable or disable mascot animations */
+  animations: boolean;
+  /** Allow mascot to enter sleep state on idle */
+  idleSleep: boolean;
+}

package/tui.tsx

@@ -0,0 +1,23 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
+import { loadMascot } from "./src/core/mascot-loader"
+import { SidebarMascot } from "./src/components/sidebar-mascot"
+
+const tui: TuiPlugin = async (api, options) => {
+  const mascot = await loadMascot(options)
+  
+  api.slots.register({
+    slots: {
+      sidebar_content() {
+        return <SidebarMascot mascot={mascot} />
+      }
+    }
+  })
+}
+
+const plugin: TuiPluginModule = {
+  id: "@mingxy/opencode-mascot",
+  tui
+}
+
+export default plugin