@doki-land/live2d-widget 0.0.0 → 0.0.11

package/README.md

@@ -1,3 +1,3 @@
 # @doki-land/live2d-widget
 
-Placeholder package (0.0.0). Reserved for doki-land/live2d.ts.
+live2d.ts package 0.0.11.

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { CreateLive2DOptions, Live2DRuntime } from '@doki-land/live2d';
+
+/**
+ * Optional page chrome for `@doki-land/live2d-widget`:
+ * speech bubble, hitokoto, and a small toolbar.
+ *
+ * Lives in the widget package so Vue / Hexo / other hosts share one shell.
+ * Host adaptors must only pass config — do not reimplement UI there.
+ */
+type WidgetToolId = "hitokoto" | "photo" | "quit";
+interface WidgetChromeOptions {
+    /** Speech bubble + page event lines. Default true when chrome is enabled. */
+    tips?: boolean;
+    /** Toolbar buttons. Default `["hitokoto", "photo", "quit"]`. */
+    tools?: WidgetToolId[];
+    /** Opening line(s). */
+    welcome?: string | string[];
+    /** Hitokoto API endpoint. Default `https://v1.hitokoto.cn`. */
+    hitokotoApi?: string;
+    /** Called after the quit tool hides the widget host. */
+    onQuit?: () => void;
+}
+interface TipMessage {
+    show(text: string | string[], timeoutMs?: number, priority?: number): void;
+    clear(): void;
+    destroy(): void;
+}
+declare const DEFAULT_WELCOME: string[];
+declare function ensureChromeStyles(doc?: Document): void;
+declare function createTipMessage(root: HTMLElement): TipMessage;
+interface ChromeSession {
+    root: HTMLElement;
+    tips: TipMessage | null;
+    destroy(): void;
+}
+declare function mountChrome(options: {
+    host: HTMLElement;
+    canvas: HTMLCanvasElement;
+    chrome: boolean | WidgetChromeOptions;
+    getCanvas: () => HTMLCanvasElement | null;
+}): ChromeSession | null;
+
+interface WidgetOptions extends CreateLive2DOptions {
+    /** CSS selector or element to host the canvas. */
+    target: string | HTMLElement;
+    /** Initial model URL (model.json / model3.json / npm:…). */
+    model?: string;
+    width?: number;
+    height?: number;
+    /** Drive PARAM_ANGLE_X with a sine while playing. Default true. */
+    autoSway?: boolean;
+    /** Start the RAF update loop after mount. Default true. */
+    autoplay?: boolean;
+    /**
+     * Optional tips bubble + toolbar (hitokoto / photo / quit).
+     * Pass `true` for defaults, or a config object.
+     */
+    chrome?: boolean | WidgetChromeOptions;
+    /** Fired when canvas hit-test finds a drawable. */
+    onHit?: (payload: {
+        area: string;
+        x: number;
+        y: number;
+    }) => void;
+}
+/**
+ * Page widget shell over `@doki-land/live2d`.
+ * Renderer fallback is `createRenderer({ prefer })` (webgpu → webgl2 → canvas2d).
+ */
+declare class Live2DWidget {
+    #private;
+    mount(options: WidgetOptions): Promise<void>;
+    destroy(): void;
+    getRuntime(): Live2DRuntime | null;
+    /** Show a tips bubble when chrome tips are enabled. */
+    showMessage(text: string | string[], timeoutMs?: number, priority?: number): void;
+}
+declare function mountWidget(options: WidgetOptions): Promise<Live2DWidget>;
+
+/**
+ * `@doki-land/live2d-widget` — browser embed helper.
+ */
+
+declare const LIVE2D_WIDGET_VERSION: "0.0.0";
+
+export { DEFAULT_WELCOME, LIVE2D_WIDGET_VERSION, Live2DWidget, type WidgetChromeOptions, type WidgetOptions, type WidgetToolId, createTipMessage, ensureChromeStyles, mountChrome, mountWidget };

package/dist/index.js

@@ -0,0 +1,399 @@
+// src/chrome.ts
+var DEFAULT_WELCOME = [
+  "\u4F60\u597D\uFF01\u6211\u662F\u770B\u677F\u5A18\uFF0C\u4ECA\u5929\u4E5F\u8981\u52A0\u6CB9\u54E6\u3002",
+  "\u6B22\u8FCE\u56DE\u6765\u2014\u2014\u70B9\u6211\u6216\u8005\u7528\u5DE5\u5177\u680F\u8DDF\u6211\u4E92\u52A8\u5427\u3002"
+];
+function pick(text) {
+  if (Array.isArray(text)) {
+    if (text.length === 0) return "";
+    return text[Math.floor(Math.random() * text.length)] ?? "";
+  }
+  return text;
+}
+var CHROME_STYLE_ID = "doki-live2d-widget-chrome-style";
+var CHROME_CSS = `
+.doki-live2d-chrome {
+  position: relative;
+  display: inline-block;
+  line-height: 0;
+  pointer-events: none;
+}
+.doki-live2d-chrome__tips {
+  position: absolute;
+  left: 12px;
+  right: 12px;
+  bottom: calc(100% - 12px);
+  z-index: 2;
+  box-sizing: border-box;
+  min-height: 2.5rem;
+  padding: 0.45rem 0.65rem;
+  border-radius: 0.65rem;
+  border: 1px solid color-mix(in srgb, #c4a574 55%, transparent);
+  background: color-mix(in srgb, #f3e6d0 82%, transparent);
+  color: #3a2a1a;
+  font: 0.82rem/1.45 ui-sans-serif, system-ui, sans-serif;
+  word-break: break-word;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.2s ease;
+}
+.doki-live2d-chrome__tips.is-active {
+  opacity: 1;
+}
+.doki-live2d-chrome__tools {
+  position: absolute;
+  right: 0;
+  bottom: 12px;
+  z-index: 2;
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+  pointer-events: auto;
+}
+.doki-live2d-chrome__tool {
+  width: 2rem;
+  height: 2rem;
+  border: 0;
+  border-radius: 999px;
+  background: color-mix(in srgb, #2a2118 78%, transparent);
+  color: #f7efe4;
+  font: 0.72rem/1 ui-sans-serif, system-ui, sans-serif;
+  cursor: pointer;
+}
+.doki-live2d-chrome__tool:hover {
+  background: #2a2118;
+}
+.doki-live2d-chrome canvas {
+  pointer-events: auto;
+  touch-action: none;
+  cursor: grab;
+}
+`;
+function ensureChromeStyles(doc = document) {
+  if (doc.getElementById(CHROME_STYLE_ID)) return;
+  const style = doc.createElement("style");
+  style.id = CHROME_STYLE_ID;
+  style.textContent = CHROME_CSS;
+  doc.head.appendChild(style);
+}
+function createTipMessage(root) {
+  const tips = document.createElement("div");
+  tips.className = "doki-live2d-chrome__tips";
+  tips.setAttribute("role", "status");
+  root.appendChild(tips);
+  let timer = 0;
+  let priority = 0;
+  return {
+    show(text, timeoutMs = 4e3, nextPriority = 1) {
+      const line = pick(text);
+      if (!line) return;
+      if (tips.classList.contains("is-active") && nextPriority < priority) {
+        return;
+      }
+      priority = nextPriority;
+      tips.textContent = line;
+      tips.classList.add("is-active");
+      if (timer) window.clearTimeout(timer);
+      timer = window.setTimeout(() => {
+        tips.classList.remove("is-active");
+        priority = 0;
+        timer = 0;
+      }, timeoutMs);
+    },
+    clear() {
+      if (timer) window.clearTimeout(timer);
+      timer = 0;
+      priority = 0;
+      tips.classList.remove("is-active");
+      tips.textContent = "";
+    },
+    destroy() {
+      this.clear();
+      tips.remove();
+    }
+  };
+}
+function bindPageTips(tips) {
+  const onCopy = () => {
+    tips.show("\u590D\u5236\u6210\u529F\u2014\u2014\u8BB0\u5F97\u6CE8\u660E\u51FA\u5904\u5440\u3002", 4e3, 2);
+  };
+  const onVisibility = () => {
+    if (document.visibilityState === "visible") {
+      tips.show("\u4F60\u56DE\u6765\u5566\uFF0C\u60F3\u6211\u4E86\u5417\uFF1F", 4e3, 2);
+    }
+  };
+  document.addEventListener("copy", onCopy);
+  document.addEventListener("visibilitychange", onVisibility);
+  return () => {
+    document.removeEventListener("copy", onCopy);
+    document.removeEventListener("visibilitychange", onVisibility);
+  };
+}
+async function fetchHitokoto(api) {
+  const res = await fetch(api);
+  if (!res.ok) throw new Error(`hitokoto HTTP ${res.status}`);
+  const data = await res.json();
+  if (!data.hitokoto) throw new Error("hitokoto empty");
+  return data.from ? `${data.hitokoto} \u2014\u2014 ${data.from}` : data.hitokoto;
+}
+function toolLabel(id) {
+  switch (id) {
+    case "hitokoto":
+      return "\u8A00";
+    case "photo":
+      return "\u62CD";
+    case "quit":
+      return "\xD7";
+  }
+}
+function mountChrome(options) {
+  if (!options.chrome) return null;
+  const cfg = options.chrome === true ? {} : options.chrome;
+  const tipsEnabled = cfg.tips !== false;
+  const tools = cfg.tools ?? ["hitokoto", "photo", "quit"];
+  ensureChromeStyles();
+  const root = document.createElement("div");
+  root.className = "doki-live2d-chrome";
+  options.host.replaceChildren(root);
+  root.appendChild(options.canvas);
+  const tips = tipsEnabled ? createTipMessage(root) : null;
+  const unbindTips = tips ? bindPageTips(tips) : () => {
+  };
+  if (tips) {
+    tips.show(cfg.welcome ?? DEFAULT_WELCOME, 5e3, 3);
+  }
+  let toolsEl = null;
+  if (tools.length > 0) {
+    toolsEl = document.createElement("div");
+    toolsEl.className = "doki-live2d-chrome__tools";
+    for (const id of tools) {
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.className = "doki-live2d-chrome__tool";
+      btn.dataset.tool = id;
+      btn.title = id;
+      btn.textContent = toolLabel(id);
+      btn.addEventListener("click", () => {
+        void (async () => {
+          if (id === "hitokoto") {
+            try {
+              const line = await fetchHitokoto(
+                cfg.hitokotoApi ?? "https://v1.hitokoto.cn"
+              );
+              tips?.show(line, 6e3, 9);
+            } catch {
+              tips?.show("\u4E00\u8A00\u83B7\u53D6\u5931\u8D25\uFF0C\u7A0D\u540E\u518D\u8BD5\u3002", 3e3, 9);
+            }
+            return;
+          }
+          if (id === "photo") {
+            const canvas = options.getCanvas();
+            if (!canvas) return;
+            tips?.show("\u5494\u5693\u2014\u2014\u7167\u7247\u4FDD\u5B58\u4E2D\u3002", 3e3, 8);
+            const url = canvas.toDataURL("image/png");
+            const a = document.createElement("a");
+            a.href = url;
+            a.download = "live2d-photo.png";
+            a.click();
+            return;
+          }
+          if (id === "quit") {
+            tips?.show("\u518D\u89C1\u5566\uFF0C\u60F3\u6211\u7684\u65F6\u5019\u518D\u53EB\u6211\u3002", 2e3, 9);
+            options.host.style.display = "none";
+            cfg.onQuit?.();
+          }
+        })();
+      });
+      toolsEl.appendChild(btn);
+    }
+    root.appendChild(toolsEl);
+  }
+  return {
+    root,
+    tips,
+    destroy() {
+      unbindTips();
+      tips?.destroy();
+      toolsEl?.remove();
+      root.remove();
+    }
+  };
+}
+
+// src/widget.ts
+import {
+  createLive2D,
+  focusParameterUpdates
+} from "@doki-land/live2d";
+var Live2DWidget = class {
+  #canvas = null;
+  #runtime = null;
+  #chrome = null;
+  #raf = 0;
+  #lastTs = 0;
+  #autoSway = true;
+  #onHit;
+  async mount(options) {
+    const host = typeof options.target === "string" ? document.querySelector(options.target) : options.target;
+    if (!host) {
+      throw new Error(
+        `@doki-land/live2d-widget: target not found: ${String(options.target)}`
+      );
+    }
+    this.destroy();
+    const width = options.width ?? 280;
+    const height = options.height ?? 400;
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    canvas.style.cssText = "display:block;width:100%;height:auto;pointer-events:auto;touch-action:none;background:transparent;cursor:grab;";
+    canvas.addEventListener("pointermove", this.#onPointerMove);
+    canvas.addEventListener("pointerdown", this.#onPointerDown);
+    const prefer = normalizePrefer(options.prefer);
+    const runtime = createLive2D({
+      backends: options.backends,
+      renderer: options.renderer,
+      prefer
+    });
+    runtime.mount(canvas);
+    this.#canvas = canvas;
+    this.#runtime = runtime;
+    this.#autoSway = options.autoSway !== false;
+    this.#onHit = options.onHit;
+    this.#chrome = mountChrome({
+      host,
+      canvas,
+      chrome: options.chrome ?? false,
+      getCanvas: () => this.#canvas
+    });
+    if (!this.#chrome) {
+      host.replaceChildren(canvas);
+    }
+    if (options.model) {
+      await runtime.loadModel(options.model);
+    }
+    if (options.autoplay !== false) {
+      this.#startLoop();
+    } else {
+      runtime.update(0);
+    }
+  }
+  destroy() {
+    this.#stopLoop();
+    if (this.#canvas) {
+      this.#canvas.removeEventListener(
+        "pointermove",
+        this.#onPointerMove
+      );
+      this.#canvas.removeEventListener(
+        "pointerdown",
+        this.#onPointerDown
+      );
+    }
+    this.#chrome?.destroy();
+    this.#chrome = null;
+    this.#runtime?.destroy();
+    this.#canvas?.remove();
+    this.#runtime = null;
+    this.#canvas = null;
+    this.#onHit = void 0;
+  }
+  getRuntime() {
+    return this.#runtime;
+  }
+  /** Show a tips bubble when chrome tips are enabled. */
+  showMessage(text, timeoutMs, priority) {
+    this.#chrome?.tips?.show(text, timeoutMs, priority);
+  }
+  #parameterFromNormalized(id, normalized) {
+    const binding = this.#runtime?.listParameters().find((p) => p.id === id);
+    if (!binding) return normalized;
+    return normalized >= 0 ? binding.defaultValue + (binding.max - binding.defaultValue) * normalized : binding.defaultValue + (binding.defaultValue - binding.min) * normalized;
+  }
+  #modelPoint(event) {
+    const canvas = this.#canvas;
+    if (!canvas) return null;
+    const rect = canvas.getBoundingClientRect();
+    if (!rect.width || !rect.height) return null;
+    return {
+      x: (event.clientX - rect.left) / rect.width * 2 - 1,
+      y: 1 - (event.clientY - rect.top) / rect.height * 2
+    };
+  }
+  #onPointerMove = (event) => {
+    const p = this.#modelPoint(event);
+    const runtime = this.#runtime;
+    if (!p || !runtime) return;
+    this.#autoSwayPausedByPointer = true;
+    for (const { id, value } of focusParameterUpdates(
+      runtime.listParameters(),
+      p.x,
+      p.y
+    )) {
+      runtime.setParameter(id, value);
+    }
+  };
+  #onPointerDown = (event) => {
+    const p = this.#modelPoint(event);
+    const runtime = this.#runtime;
+    if (!p || !runtime) return;
+    const area = runtime.hitTest(p.x, p.y);
+    if (area) {
+      this.#onHit?.({ area, x: p.x, y: p.y });
+      this.#chrome?.tips?.show("\u78B0\u5230\u6211\u5566\uFF5E", 2500, 4);
+    }
+  };
+  #autoSwayPausedByPointer = false;
+  #startLoop() {
+    this.#stopLoop();
+    const tick = (ts) => {
+      const runtime = this.#runtime;
+      if (!runtime) return;
+      const dt = this.#lastTs ? (ts - this.#lastTs) / 1e3 : 0;
+      this.#lastTs = ts;
+      if (this.#autoSway && !this.#autoSwayPausedByPointer) {
+        runtime.setParameter(
+          "PARAM_ANGLE_X",
+          this.#parameterFromNormalized(
+            "PARAM_ANGLE_X",
+            Math.sin(ts / 1e3) * 0.25
+          )
+        );
+      }
+      if (this.#autoSwayPausedByPointer) {
+        this.#autoSwayPausedByPointer = false;
+      }
+      runtime.update(dt);
+      this.#raf = requestAnimationFrame(tick);
+    };
+    this.#raf = requestAnimationFrame(tick);
+  }
+  #stopLoop() {
+    if (this.#raf) cancelAnimationFrame(this.#raf);
+    this.#raf = 0;
+    this.#lastTs = 0;
+  }
+};
+function normalizePrefer(prefer) {
+  if (!prefer?.length) return void 0;
+  const allowed = /* @__PURE__ */ new Set(["webgpu", "webgl2", "canvas2d"]);
+  const out = prefer.filter((k) => allowed.has(k));
+  return out.length ? out : void 0;
+}
+async function mountWidget(options) {
+  const widget = new Live2DWidget();
+  await widget.mount(options);
+  return widget;
+}
+
+// src/index.ts
+var LIVE2D_WIDGET_VERSION = "0.0.0";
+export {
+  DEFAULT_WELCOME,
+  LIVE2D_WIDGET_VERSION,
+  Live2DWidget,
+  createTipMessage,
+  ensureChromeStyles,
+  mountChrome,
+  mountWidget
+};

package/package.json

@@ -1,7 +1,46 @@
 {
   "name": "@doki-land/live2d-widget",
-  "version": "0.0.0",
-  "description": "live2d.ts placeholder — not for production use.",
+  "version": "0.0.11",
+  "description": "Browser canvas widget for @doki-land/live2d",
+  "type": "module",
   "license": "MIT",
-  "private": false
+  "author": "Doki Land",
+  "keywords": [
+    "live2d",
+    "widget",
+    "doki-land"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@doki-land/live2d": "0.0.11"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/live2d.ts.git"
+  }
 }

package/src/chrome.ts

@@ -0,0 +1,283 @@
+/**
+ * Optional page chrome for `@doki-land/live2d-widget`:
+ * speech bubble, hitokoto, and a small toolbar.
+ *
+ * Lives in the widget package so Vue / Hexo / other hosts share one shell.
+ * Host adaptors must only pass config — do not reimplement UI there.
+ */
+
+export type WidgetToolId = "hitokoto" | "photo" | "quit";
+
+export interface WidgetChromeOptions {
+    /** Speech bubble + page event lines. Default true when chrome is enabled. */
+    tips?: boolean;
+    /** Toolbar buttons. Default `["hitokoto", "photo", "quit"]`. */
+    tools?: WidgetToolId[];
+    /** Opening line(s). */
+    welcome?: string | string[];
+    /** Hitokoto API endpoint. Default `https://v1.hitokoto.cn`. */
+    hitokotoApi?: string;
+    /** Called after the quit tool hides the widget host. */
+    onQuit?: () => void;
+}
+
+export interface TipMessage {
+    show(text: string | string[], timeoutMs?: number, priority?: number): void;
+    clear(): void;
+    destroy(): void;
+}
+
+const DEFAULT_WELCOME = [
+    "你好！我是看板娘，今天也要加油哦。",
+    "欢迎回来——点我或者用工具栏跟我互动吧。",
+];
+
+function pick(text: string | string[]): string {
+    if (Array.isArray(text)) {
+        if (text.length === 0) return "";
+        return text[Math.floor(Math.random() * text.length)] ?? "";
+    }
+    return text;
+}
+
+const CHROME_STYLE_ID = "doki-live2d-widget-chrome-style";
+
+const CHROME_CSS = `
+.doki-live2d-chrome {
+  position: relative;
+  display: inline-block;
+  line-height: 0;
+  pointer-events: none;
+}
+.doki-live2d-chrome__tips {
+  position: absolute;
+  left: 12px;
+  right: 12px;
+  bottom: calc(100% - 12px);
+  z-index: 2;
+  box-sizing: border-box;
+  min-height: 2.5rem;
+  padding: 0.45rem 0.65rem;
+  border-radius: 0.65rem;
+  border: 1px solid color-mix(in srgb, #c4a574 55%, transparent);
+  background: color-mix(in srgb, #f3e6d0 82%, transparent);
+  color: #3a2a1a;
+  font: 0.82rem/1.45 ui-sans-serif, system-ui, sans-serif;
+  word-break: break-word;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.2s ease;
+}
+.doki-live2d-chrome__tips.is-active {
+  opacity: 1;
+}
+.doki-live2d-chrome__tools {
+  position: absolute;
+  right: 0;
+  bottom: 12px;
+  z-index: 2;
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+  pointer-events: auto;
+}
+.doki-live2d-chrome__tool {
+  width: 2rem;
+  height: 2rem;
+  border: 0;
+  border-radius: 999px;
+  background: color-mix(in srgb, #2a2118 78%, transparent);
+  color: #f7efe4;
+  font: 0.72rem/1 ui-sans-serif, system-ui, sans-serif;
+  cursor: pointer;
+}
+.doki-live2d-chrome__tool:hover {
+  background: #2a2118;
+}
+.doki-live2d-chrome canvas {
+  pointer-events: auto;
+  touch-action: none;
+  cursor: grab;
+}
+`;
+
+export function ensureChromeStyles(doc: Document = document): void {
+    if (doc.getElementById(CHROME_STYLE_ID)) return;
+    const style = doc.createElement("style");
+    style.id = CHROME_STYLE_ID;
+    style.textContent = CHROME_CSS;
+    doc.head.appendChild(style);
+}
+
+export function createTipMessage(root: HTMLElement): TipMessage {
+    const tips = document.createElement("div");
+    tips.className = "doki-live2d-chrome__tips";
+    tips.setAttribute("role", "status");
+    root.appendChild(tips);
+
+    let timer = 0;
+    let priority = 0;
+
+    return {
+        show(text, timeoutMs = 4000, nextPriority = 1) {
+            const line = pick(text);
+            if (!line) return;
+            if (
+                tips.classList.contains("is-active") &&
+                nextPriority < priority
+            ) {
+                return;
+            }
+            priority = nextPriority;
+            tips.textContent = line;
+            tips.classList.add("is-active");
+            if (timer) window.clearTimeout(timer);
+            timer = window.setTimeout(() => {
+                tips.classList.remove("is-active");
+                priority = 0;
+                timer = 0;
+            }, timeoutMs);
+        },
+        clear() {
+            if (timer) window.clearTimeout(timer);
+            timer = 0;
+            priority = 0;
+            tips.classList.remove("is-active");
+            tips.textContent = "";
+        },
+        destroy() {
+            this.clear();
+            tips.remove();
+        },
+    };
+}
+
+export interface ChromeSession {
+    root: HTMLElement;
+    tips: TipMessage | null;
+    destroy(): void;
+}
+
+function bindPageTips(tips: TipMessage): () => void {
+    const onCopy = () => {
+        tips.show("复制成功——记得注明出处呀。", 4000, 2);
+    };
+    const onVisibility = () => {
+        if (document.visibilityState === "visible") {
+            tips.show("你回来啦，想我了吗？", 4000, 2);
+        }
+    };
+    document.addEventListener("copy", onCopy);
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => {
+        document.removeEventListener("copy", onCopy);
+        document.removeEventListener("visibilitychange", onVisibility);
+    };
+}
+
+async function fetchHitokoto(api: string): Promise<string> {
+    const res = await fetch(api);
+    if (!res.ok) throw new Error(`hitokoto HTTP ${res.status}`);
+    const data = (await res.json()) as { hitokoto?: string; from?: string };
+    if (!data.hitokoto) throw new Error("hitokoto empty");
+    return data.from ? `${data.hitokoto} —— ${data.from}` : data.hitokoto;
+}
+
+function toolLabel(id: WidgetToolId): string {
+    switch (id) {
+        case "hitokoto":
+            return "言";
+        case "photo":
+            return "拍";
+        case "quit":
+            return "×";
+    }
+}
+
+export function mountChrome(options: {
+    host: HTMLElement;
+    canvas: HTMLCanvasElement;
+    chrome: boolean | WidgetChromeOptions;
+    getCanvas: () => HTMLCanvasElement | null;
+}): ChromeSession | null {
+    if (!options.chrome) return null;
+    const cfg: WidgetChromeOptions =
+        options.chrome === true ? {} : options.chrome;
+    const tipsEnabled = cfg.tips !== false;
+    const tools =
+        cfg.tools ?? (["hitokoto", "photo", "quit"] as WidgetToolId[]);
+
+    ensureChromeStyles();
+
+    const root = document.createElement("div");
+    root.className = "doki-live2d-chrome";
+    options.host.replaceChildren(root);
+    root.appendChild(options.canvas);
+
+    const tips = tipsEnabled ? createTipMessage(root) : null;
+    const unbindTips = tips ? bindPageTips(tips) : () => {};
+
+    if (tips) {
+        tips.show(cfg.welcome ?? DEFAULT_WELCOME, 5000, 3);
+    }
+
+    let toolsEl: HTMLElement | null = null;
+    if (tools.length > 0) {
+        toolsEl = document.createElement("div");
+        toolsEl.className = "doki-live2d-chrome__tools";
+        for (const id of tools) {
+            const btn = document.createElement("button");
+            btn.type = "button";
+            btn.className = "doki-live2d-chrome__tool";
+            btn.dataset.tool = id;
+            btn.title = id;
+            btn.textContent = toolLabel(id);
+            btn.addEventListener("click", () => {
+                void (async () => {
+                    if (id === "hitokoto") {
+                        try {
+                            const line = await fetchHitokoto(
+                                cfg.hitokotoApi ?? "https://v1.hitokoto.cn",
+                            );
+                            tips?.show(line, 6000, 9);
+                        } catch {
+                            tips?.show("一言获取失败，稍后再试。", 3000, 9);
+                        }
+                        return;
+                    }
+                    if (id === "photo") {
+                        const canvas = options.getCanvas();
+                        if (!canvas) return;
+                        tips?.show("咔嚓——照片保存中。", 3000, 8);
+                        const url = canvas.toDataURL("image/png");
+                        const a = document.createElement("a");
+                        a.href = url;
+                        a.download = "live2d-photo.png";
+                        a.click();
+                        return;
+                    }
+                    if (id === "quit") {
+                        tips?.show("再见啦，想我的时候再叫我。", 2000, 9);
+                        options.host.style.display = "none";
+                        cfg.onQuit?.();
+                    }
+                })();
+            });
+            toolsEl.appendChild(btn);
+        }
+        root.appendChild(toolsEl);
+    }
+
+    return {
+        root,
+        tips,
+        destroy() {
+            unbindTips();
+            tips?.destroy();
+            toolsEl?.remove();
+            root.remove();
+        },
+    };
+}
+
+export { DEFAULT_WELCOME };

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * `@doki-land/live2d-widget` — browser embed helper.
+ */
+
+export {
+    createTipMessage,
+    DEFAULT_WELCOME,
+    ensureChromeStyles,
+    mountChrome,
+} from "./chrome.js";
+export {
+    Live2DWidget,
+    mountWidget,
+    type WidgetChromeOptions,
+    type WidgetOptions,
+    type WidgetToolId,
+} from "./widget.js";
+
+export const LIVE2D_WIDGET_VERSION = "0.0.0" as const;

package/src/widget.ts

@@ -0,0 +1,238 @@
+import {
+    type CreateLive2DOptions,
+    createLive2D,
+    focusParameterUpdates,
+    type Live2DRuntime,
+    type RendererKind,
+} from "@doki-land/live2d";
+import {
+    type ChromeSession,
+    mountChrome,
+    type WidgetChromeOptions,
+} from "./chrome.js";
+
+export type { WidgetChromeOptions, WidgetToolId } from "./chrome.js";
+
+export interface WidgetOptions extends CreateLive2DOptions {
+    /** CSS selector or element to host the canvas. */
+    target: string | HTMLElement;
+    /** Initial model URL (model.json / model3.json / npm:…). */
+    model?: string;
+    width?: number;
+    height?: number;
+    /** Drive PARAM_ANGLE_X with a sine while playing. Default true. */
+    autoSway?: boolean;
+    /** Start the RAF update loop after mount. Default true. */
+    autoplay?: boolean;
+    /**
+     * Optional tips bubble + toolbar (hitokoto / photo / quit).
+     * Pass `true` for defaults, or a config object.
+     */
+    chrome?: boolean | WidgetChromeOptions;
+    /** Fired when canvas hit-test finds a drawable. */
+    onHit?: (payload: { area: string; x: number; y: number }) => void;
+}
+
+/**
+ * Page widget shell over `@doki-land/live2d`.
+ * Renderer fallback is `createRenderer({ prefer })` (webgpu → webgl2 → canvas2d).
+ */
+export class Live2DWidget {
+    #canvas: HTMLCanvasElement | null = null;
+    #runtime: Live2DRuntime | null = null;
+    #chrome: ChromeSession | null = null;
+    #raf = 0;
+    #lastTs = 0;
+    #autoSway = true;
+    #onHit: WidgetOptions["onHit"];
+
+    async mount(options: WidgetOptions): Promise<void> {
+        const host =
+            typeof options.target === "string"
+                ? document.querySelector<HTMLElement>(options.target)
+                : options.target;
+        if (!host) {
+            throw new Error(
+                `@doki-land/live2d-widget: target not found: ${String(options.target)}`,
+            );
+        }
+
+        this.destroy();
+
+        const width = options.width ?? 280;
+        const height = options.height ?? 400;
+        const canvas = document.createElement("canvas");
+        canvas.width = width;
+        canvas.height = height;
+        canvas.style.cssText =
+            "display:block;width:100%;height:auto;pointer-events:auto;touch-action:none;background:transparent;cursor:grab;";
+        canvas.addEventListener("pointermove", this.#onPointerMove);
+        canvas.addEventListener("pointerdown", this.#onPointerDown);
+
+        const prefer = normalizePrefer(options.prefer);
+        const runtime = createLive2D({
+            backends: options.backends,
+            renderer: options.renderer,
+            prefer,
+        });
+        runtime.mount(canvas);
+
+        this.#canvas = canvas;
+        this.#runtime = runtime;
+        this.#autoSway = options.autoSway !== false;
+        this.#onHit = options.onHit;
+        this.#chrome = mountChrome({
+            host,
+            canvas,
+            chrome: options.chrome ?? false,
+            getCanvas: () => this.#canvas,
+        });
+        if (!this.#chrome) {
+            host.replaceChildren(canvas);
+        }
+
+        if (options.model) {
+            await runtime.loadModel(options.model);
+        }
+
+        if (options.autoplay !== false) {
+            this.#startLoop();
+        } else {
+            runtime.update(0);
+        }
+    }
+
+    destroy(): void {
+        this.#stopLoop();
+        if (this.#canvas) {
+            this.#canvas.removeEventListener(
+                "pointermove",
+                this.#onPointerMove,
+            );
+            this.#canvas.removeEventListener(
+                "pointerdown",
+                this.#onPointerDown,
+            );
+        }
+        this.#chrome?.destroy();
+        this.#chrome = null;
+        this.#runtime?.destroy();
+        this.#canvas?.remove();
+        this.#runtime = null;
+        this.#canvas = null;
+        this.#onHit = undefined;
+    }
+
+    getRuntime(): Live2DRuntime | null {
+        return this.#runtime;
+    }
+
+    /** Show a tips bubble when chrome tips are enabled. */
+    showMessage(
+        text: string | string[],
+        timeoutMs?: number,
+        priority?: number,
+    ): void {
+        this.#chrome?.tips?.show(text, timeoutMs, priority);
+    }
+
+    #parameterFromNormalized(id: string, normalized: number): number {
+        const binding = this.#runtime
+            ?.listParameters()
+            .find((p) => p.id === id);
+        if (!binding) return normalized;
+        return normalized >= 0
+            ? binding.defaultValue +
+                  (binding.max - binding.defaultValue) * normalized
+            : binding.defaultValue +
+                  (binding.defaultValue - binding.min) * normalized;
+    }
+
+    #modelPoint(event: PointerEvent): { x: number; y: number } | null {
+        const canvas = this.#canvas;
+        if (!canvas) return null;
+        const rect = canvas.getBoundingClientRect();
+        if (!rect.width || !rect.height) return null;
+        return {
+            x: ((event.clientX - rect.left) / rect.width) * 2 - 1,
+            y: 1 - ((event.clientY - rect.top) / rect.height) * 2,
+        };
+    }
+
+    #onPointerMove = (event: PointerEvent): void => {
+        const p = this.#modelPoint(event);
+        const runtime = this.#runtime;
+        if (!p || !runtime) return;
+        // Pointer tracking overrides auto-sway for ANGLE_X while moving.
+        this.#autoSwayPausedByPointer = true;
+        for (const { id, value } of focusParameterUpdates(
+            runtime.listParameters(),
+            p.x,
+            p.y,
+        )) {
+            runtime.setParameter(id, value);
+        }
+    };
+
+    #onPointerDown = (event: PointerEvent): void => {
+        const p = this.#modelPoint(event);
+        const runtime = this.#runtime;
+        if (!p || !runtime) return;
+        const area = runtime.hitTest(p.x, p.y);
+        if (area) {
+            this.#onHit?.({ area, x: p.x, y: p.y });
+            this.#chrome?.tips?.show("碰到我啦～", 2500, 4);
+        }
+    };
+
+    #autoSwayPausedByPointer = false;
+
+    #startLoop(): void {
+        this.#stopLoop();
+        const tick = (ts: number) => {
+            const runtime = this.#runtime;
+            if (!runtime) return;
+            const dt = this.#lastTs ? (ts - this.#lastTs) / 1000 : 0;
+            this.#lastTs = ts;
+            if (this.#autoSway && !this.#autoSwayPausedByPointer) {
+                runtime.setParameter(
+                    "PARAM_ANGLE_X",
+                    this.#parameterFromNormalized(
+                        "PARAM_ANGLE_X",
+                        Math.sin(ts / 1000) * 0.25,
+                    ),
+                );
+            }
+            // Resume sway shortly after the last pointer sample.
+            if (this.#autoSwayPausedByPointer) {
+                this.#autoSwayPausedByPointer = false;
+            }
+            runtime.update(dt);
+            this.#raf = requestAnimationFrame(tick);
+        };
+        this.#raf = requestAnimationFrame(tick);
+    }
+
+    #stopLoop(): void {
+        if (this.#raf) cancelAnimationFrame(this.#raf);
+        this.#raf = 0;
+        this.#lastTs = 0;
+    }
+}
+
+function normalizePrefer(
+    prefer: RendererKind[] | undefined,
+): RendererKind[] | undefined {
+    if (!prefer?.length) return undefined;
+    const allowed = new Set<RendererKind>(["webgpu", "webgl2", "canvas2d"]);
+    const out = prefer.filter((k): k is RendererKind => allowed.has(k));
+    return out.length ? out : undefined;
+}
+
+export async function mountWidget(
+    options: WidgetOptions,
+): Promise<Live2DWidget> {
+    const widget = new Live2DWidget();
+    await widget.mount(options);
+    return widget;
+}