@doki-land/live2d-element 0.0.23 → 0.0.24

package/README.md

@@ -1,12 +1,14 @@
 # `@doki-land/live2d-element`
 
-Official `<live-2d>` Custom Element — thin host over `@doki-land/live2d` with Stage-owned RAF.
+Official `<live-2d>` / `<live-2d-widget>` Custom Elements — thin hosts over
+`@doki-land/live2d` with Stage-owned RAF.
 
 ## Status (Developer Preview)
 
-v0.0.22 thin gate: pure TypeScript `customElements.define('live-2d', …)`. Zero VMZ runtime dependency on this package or on `@doki-land/live2d*`.
+Pure TypeScript `customElements.define`. Zero VMZ runtime dependency.
+Primary TS symbols use the `Live2d*` / `createLive2d*` spelling (see design `00` §4.4).
 
-HTML Custom Elements require a hyphen; the registered tag is **`live-2d`** (not unhyphenated `live2d`). Design `01` still targets eventual `vmz build --target custom-element` when that CLI target ships.
+HTML Custom Elements require a hyphen; tags are **`live-2d`** and **`live-2d-widget`**.
 
 ## Install
 
@@ -26,12 +28,19 @@ pnpm add @doki-land/live2d-element
   width="320"
   height="320"
   autoplay
+  interactive
+  tracking="pointer"
 ></live-2d>
 <script type="module">
   const el = document.querySelector("live-2d");
   el.addEventListener("live2d-ready", () => console.log("ready"));
+  el.addEventListener("live2d-hit", (e) => console.log(e.detail));
   el.addEventListener("live2d-error", (e) => console.error(e.detail));
+  // Methods: loadModel / playMotion / setExpression / lookAt / pause / resume
 </script>
 ```
 
+`<live-2d-widget>` nests an inner `<live-2d>` and forwards model/size attributes
+(product-shell chrome POC; no second Stage clock).
+
 See `fixtures/index.html` for a native HTML dogfood page.

package/dist/index.d.ts

@@ -1,12 +1,17 @@
-import { Live2DRuntime } from '@doki-land/live2d';
+import { Live2dRuntime, PlayMotionOptions } from '@doki-land/live2d';
 
 /** Idempotent `customElements.define('live-2d', …)`. */
 declare function defineLive2dElement(): void;
+/** Idempotent `customElements.define('live-2d-widget', …)`. */
+declare function defineLive2dWidgetElement(): void;
+/** Register both official CE tags. */
+declare function defineLive2dElements(): void;
 
 declare const LIVE2D_ELEMENT_TAG: "live-2d";
 type Live2dElementRenderer = "auto" | "webgpu" | "webgl2" | "canvas2d";
+type Live2dElementTracking = "pointer" | "none";
 /**
- * Thin `<live-2d>` host: attribute → createLive2D → Stage RAF → live2d-* events.
+ * Thin `<live-2d>` host: attribute → createLive2d → Stage RAF → live2d-* events.
  */
 declare class Live2dElement extends HTMLElement {
     #private;
@@ -21,12 +26,50 @@ declare class Live2dElement extends HTMLElement {
     set height(value: number);
     get autoplay(): boolean;
     set autoplay(value: boolean);
-    get runtime(): Live2DRuntime | null;
+    get interactive(): boolean;
+    set interactive(value: boolean);
+    get tracking(): Live2dElementTracking;
+    set tracking(value: Live2dElementTracking);
+    get runtime(): Live2dRuntime | null;
     /** Imperative reload (also used when `model` attribute changes). */
-    loadModel(source?: string): Promise<void>;
+    loadModel(source?: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    playMotion(group: string, index?: number, options?: PlayMotionOptions): Promise<boolean>;
+    setExpression(name: string | null): Promise<boolean>;
+    /** Stage-normalized look-at in [-1, 1] client-mapped coords (x right, y up). */
+    lookAt(x: number, y: number): void;
+    pause(): void;
+    resume(): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
 }
 
-export { LIVE2D_ELEMENT_TAG, Live2dElement, type Live2dElementRenderer, defineLive2dElement };
+declare const LIVE2D_WIDGET_ELEMENT_TAG: "live-2d-widget";
+/**
+ * Thin `<live-2d-widget>` product-shell CE (v0.0.24 POC).
+ *
+ * Owns chrome layout only; delegates model/RAF/hit to an inner `<live-2d>`.
+ * Does not create a second Stage clock.
+ */
+declare class Live2dWidgetElement extends HTMLElement {
+    #private;
+    static get observedAttributes(): string[];
+    get model(): string;
+    set model(value: string);
+    get renderer(): string;
+    set renderer(value: string);
+    get width(): number;
+    set width(value: number);
+    get height(): number;
+    set height(value: number);
+    get autoplay(): boolean;
+    set autoplay(value: boolean);
+    /** Inner `<live-2d>` when present. */
+    get actor(): Live2dElement | null;
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+}
+
+export { LIVE2D_ELEMENT_TAG, LIVE2D_WIDGET_ELEMENT_TAG, Live2dElement, type Live2dElementRenderer, type Live2dElementTracking, Live2dWidgetElement, defineLive2dElement, defineLive2dElements, defineLive2dWidgetElement };

package/dist/index.js

@@ -1,7 +1,17 @@
 // src/live2d-element.ts
-import { createLive2D } from "@doki-land/live2d";
+import {
+  createLive2d
+} from "@doki-land/live2d";
 var LIVE2D_ELEMENT_TAG = "live-2d";
-var OBSERVED = ["model", "renderer", "width", "height", "autoplay"];
+var OBSERVED = [
+  "model",
+  "renderer",
+  "width",
+  "height",
+  "autoplay",
+  "interactive",
+  "tracking"
+];
 function preferFromRenderer(renderer) {
   if (renderer === "webgpu") return ["webgpu", "webgl2", "canvas2d"];
   if (renderer === "webgl2") return ["webgl2", "canvas2d", "webgpu"];
@@ -27,7 +37,11 @@ var Live2dElement = class extends HTMLElement {
   #width = 320;
   #height = 320;
   #autoplay = true;
+  #interactive = false;
+  #tracking = "none";
   #connected = false;
+  #boundPointer = null;
+  #unsubs = [];
   get model() {
     return this.#model;
   }
@@ -61,15 +75,52 @@ var Live2dElement = class extends HTMLElement {
     if (value) this.setAttribute("autoplay", "");
     else this.removeAttribute("autoplay");
   }
+  get interactive() {
+    return this.#interactive;
+  }
+  set interactive(value) {
+    if (value) this.setAttribute("interactive", "");
+    else this.removeAttribute("interactive");
+  }
+  get tracking() {
+    return this.#tracking;
+  }
+  set tracking(value) {
+    this.setAttribute("tracking", value === "pointer" ? "pointer" : "none");
+  }
   get runtime() {
     return this.#runtime;
   }
   /** Imperative reload (also used when `model` attribute changes). */
-  async loadModel(source) {
+  async loadModel(source, opts) {
     if (source !== void 0) {
       this.model = String(source);
     }
-    await this.#boot();
+    await this.#boot(opts?.signal);
+  }
+  playMotion(group, index, options) {
+    return this.#runtime?.playMotion(group, index, options) ?? Promise.resolve(false);
+  }
+  setExpression(name) {
+    return this.#runtime?.setExpression(name) ?? Promise.resolve(false);
+  }
+  /** Stage-normalized look-at in [-1, 1] client-mapped coords (x right, y up). */
+  lookAt(x, y) {
+    const stageX = (Number(x) + 1) / 2;
+    const stageY = (1 - Number(y)) / 2;
+    this.#runtime?.actor.lookAt(stageX, stageY);
+  }
+  pause() {
+    this.#runtime?.stage.pause();
+  }
+  resume() {
+    this.#runtime?.stage.resume();
+    if (this.#autoplay) {
+      try {
+        this.#runtime?.stage.start();
+      } catch {
+      }
+    }
   }
   connectedCallback() {
     this.#connected = true;
@@ -109,6 +160,16 @@ var Live2dElement = class extends HTMLElement {
         if (this.#autoplay) this.#runtime.stage.start();
         else this.#runtime.stage.pause();
       }
+      return;
+    }
+    if (name === "interactive") {
+      this.#interactive = parseBoolAttr(this, "interactive", false);
+      this.#syncPointer();
+      return;
+    }
+    if (name === "tracking") {
+      this.#tracking = value === "pointer" ? "pointer" : "none";
+      this.#syncPointer();
     }
   }
   #readAttributes() {
@@ -131,6 +192,8 @@ var Live2dElement = class extends HTMLElement {
       );
     }
     this.#autoplay = parseBoolAttr(this, "autoplay", true);
+    this.#interactive = parseBoolAttr(this, "interactive", false);
+    this.#tracking = this.getAttribute("tracking") === "pointer" ? "pointer" : "none";
   }
   #ensureCanvas() {
     if (this.#canvas?.isConnected) return this.#canvas;
@@ -153,7 +216,62 @@ var Live2dElement = class extends HTMLElement {
     this.style.display = this.style.display || "inline-block";
     this.#runtime?.stage.resize?.(this.#width, this.#height);
   }
+  #clearUnsubs() {
+    for (const off of this.#unsubs) {
+      try {
+        off();
+      } catch {
+      }
+    }
+    this.#unsubs = [];
+  }
+  #detachPointer() {
+    if (this.#canvas && this.#boundPointer) {
+      this.#canvas.removeEventListener("pointerdown", this.#boundPointer);
+      this.#canvas.removeEventListener("pointermove", this.#boundPointer);
+    }
+    this.#boundPointer = null;
+  }
+  #syncPointer() {
+    this.#detachPointer();
+    const canvas = this.#canvas;
+    const runtime = this.#runtime;
+    if (!canvas || !runtime) return;
+    if (!this.#interactive && this.#tracking !== "pointer") return;
+    this.#boundPointer = (event) => {
+      const rect = canvas.getBoundingClientRect();
+      if (rect.width <= 0 || rect.height <= 0) return;
+      const nx = (event.clientX - rect.left) / rect.width * 2 - 1;
+      const ny = 1 - (event.clientY - rect.top) / rect.height * 2;
+      if (this.#tracking === "pointer" || event.type === "pointermove") {
+        this.lookAt(nx, ny);
+      }
+      if (this.#interactive && event.type === "pointerdown") {
+        const area = runtime.hitTest(nx, ny);
+        this.dispatchEvent(
+          new CustomEvent("live2d-hit", {
+            bubbles: true,
+            composed: true,
+            detail: {
+              area,
+              modelX: nx,
+              modelY: ny,
+              originalEvent: event
+            }
+          })
+        );
+      }
+    };
+    if (this.#interactive) {
+      canvas.addEventListener("pointerdown", this.#boundPointer);
+    }
+    if (this.#tracking === "pointer") {
+      canvas.addEventListener("pointermove", this.#boundPointer);
+    }
+  }
   #destroyRuntime() {
+    this.#clearUnsubs();
+    this.#detachPointer();
     try {
       this.#runtime?.stage.stop?.();
     } catch {
@@ -163,17 +281,26 @@ var Live2dElement = class extends HTMLElement {
     this.removeAttribute("data-phase");
     this.removeAttribute("aria-busy");
   }
-  async #boot() {
+  async #boot(signal) {
     if (!this.#connected) return;
     const model = this.#model.trim();
     if (!model) return;
     const gen = ++this.#mountGen;
     this.#destroyRuntime();
+    if (signal?.aborted) {
+      this.#emitError(signal.reason ?? new Error("aborted"));
+      return;
+    }
+    const onAbort = () => {
+      this.#mountGen += 1;
+      this.#destroyRuntime();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
     const canvas = this.#ensureCanvas();
     this.setAttribute("data-phase", "loading");
     this.setAttribute("aria-busy", "true");
     try {
-      const runtime = createLive2D({
+      const runtime = createLive2d({
         prefer: preferFromRenderer(this.#renderer),
         updateMode: "auto"
       });
@@ -181,38 +308,70 @@ var Live2dElement = class extends HTMLElement {
         runtime.destroy();
         return;
       }
-      runtime.events.on("ready", () => {
-        if (gen !== this.#mountGen) return;
-        this.setAttribute("data-phase", "live");
-        this.setAttribute("aria-busy", "false");
-        if (this.#autoplay) {
-          try {
-            runtime.stage.start();
-          } catch {
+      this.#unsubs.push(
+        runtime.events.on("ready", () => {
+          if (gen !== this.#mountGen) return;
+          this.setAttribute("data-phase", "live");
+          this.setAttribute("aria-busy", "false");
+          if (this.#autoplay) {
+            try {
+              runtime.stage.start();
+            } catch {
+            }
           }
-        }
-        this.dispatchEvent(
-          new CustomEvent("live2d-ready", {
-            bubbles: true,
-            composed: true,
-            detail: { model }
-          })
-        );
-      });
-      runtime.events.on("error", (payload) => {
-        if (gen !== this.#mountGen) return;
-        this.#emitError(payload?.error ?? "load error");
-      });
+          this.#syncPointer();
+          this.dispatchEvent(
+            new CustomEvent("live2d-ready", {
+              bubbles: true,
+              composed: true,
+              detail: { model }
+            })
+          );
+        })
+      );
+      this.#unsubs.push(
+        runtime.events.on("error", (payload) => {
+          if (gen !== this.#mountGen) return;
+          this.#emitError(payload?.error ?? "load error");
+        })
+      );
+      this.#unsubs.push(
+        runtime.events.on("motion:start", (payload) => {
+          if (gen !== this.#mountGen) return;
+          this.dispatchEvent(
+            new CustomEvent("live2d-motion-start", {
+              bubbles: true,
+              composed: true,
+              detail: payload
+            })
+          );
+        })
+      );
+      this.#unsubs.push(
+        runtime.events.on("motion:finish", (payload) => {
+          if (gen !== this.#mountGen) return;
+          this.dispatchEvent(
+            new CustomEvent("live2d-motion-finish", {
+              bubbles: true,
+              composed: true,
+              detail: payload
+            })
+          );
+        })
+      );
       runtime.mount(canvas);
-      await runtime.loadModel(model);
+      await runtime.loadModel(model, void 0, { signal });
       if (gen !== this.#mountGen) {
         runtime.destroy();
         return;
       }
       this.#runtime = runtime;
+      this.#syncPointer();
     } catch (err) {
       if (gen !== this.#mountGen) return;
       this.#emitError(err);
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
     }
   }
   #emitError(error) {
@@ -231,23 +390,137 @@ var Live2dElement = class extends HTMLElement {
   }
 };
 
+// src/live2d-widget-element.ts
+var LIVE2D_WIDGET_ELEMENT_TAG = "live-2d-widget";
+var OBSERVED2 = ["model", "renderer", "width", "height", "autoplay"];
+var Live2dWidgetElement = class extends HTMLElement {
+  static get observedAttributes() {
+    return [...OBSERVED2];
+  }
+  #host = null;
+  #actor = null;
+  get model() {
+    return this.getAttribute("model") ?? "";
+  }
+  set model(value) {
+    const next = String(value ?? "");
+    if (next) this.setAttribute("model", next);
+    else this.removeAttribute("model");
+  }
+  get renderer() {
+    return this.getAttribute("renderer") ?? "auto";
+  }
+  set renderer(value) {
+    this.setAttribute("renderer", value || "auto");
+  }
+  get width() {
+    return Math.max(1, Number(this.getAttribute("width")) || 320);
+  }
+  set width(value) {
+    this.setAttribute("width", String(Math.max(1, Number(value) || 320)));
+  }
+  get height() {
+    return Math.max(1, Number(this.getAttribute("height")) || 320);
+  }
+  set height(value) {
+    this.setAttribute("height", String(Math.max(1, Number(value) || 320)));
+  }
+  get autoplay() {
+    if (!this.hasAttribute("autoplay")) return true;
+    const v = this.getAttribute("autoplay");
+    if (v === null || v === "" || v === "autoplay") return true;
+    return v !== "false" && v !== "0";
+  }
+  set autoplay(value) {
+    if (value) this.setAttribute("autoplay", "");
+    else this.removeAttribute("autoplay");
+  }
+  /** Inner `<live-2d>` when present. */
+  get actor() {
+    return this.#actor;
+  }
+  connectedCallback() {
+    defineLive2dElement();
+    this.#ensureDom();
+    this.#syncActorFromAttributes();
+  }
+  attributeChangedCallback() {
+    if (!this.isConnected) return;
+    this.#syncActorFromAttributes();
+  }
+  #ensureDom() {
+    if (this.#host?.isConnected) return;
+    let actor = this.querySelector(
+      LIVE2D_ELEMENT_TAG
+    );
+    if (!actor) {
+      actor = document.createElement(LIVE2D_ELEMENT_TAG);
+    } else {
+      actor.remove();
+    }
+    this.replaceChildren();
+    const host = document.createElement("div");
+    host.setAttribute("part", "chrome");
+    host.className = "live2d-widget-chrome";
+    host.appendChild(actor);
+    this.appendChild(host);
+    this.#host = host;
+    this.#actor = actor;
+  }
+  #syncActorFromAttributes() {
+    this.#ensureDom();
+    const actor = this.#actor;
+    if (!actor) return;
+    if (this.hasAttribute("model")) {
+      actor.setAttribute("model", this.model);
+    }
+    if (this.hasAttribute("renderer")) {
+      actor.setAttribute("renderer", this.renderer);
+    }
+    actor.setAttribute("width", String(this.width));
+    actor.setAttribute("height", String(this.height));
+    if (this.autoplay) actor.setAttribute("autoplay", "");
+    else actor.removeAttribute("autoplay");
+  }
+};
+
 // src/define.ts
-var defined = false;
+var elementDefined = false;
+var widgetDefined = false;
 function defineLive2dElement() {
-  if (defined) return;
+  if (elementDefined) return;
   if (typeof customElements === "undefined") return;
   if (customElements.get(LIVE2D_ELEMENT_TAG)) {
-    defined = true;
+    elementDefined = true;
     return;
   }
   customElements.define(LIVE2D_ELEMENT_TAG, Live2dElement);
-  defined = true;
+  elementDefined = true;
+}
+function defineLive2dWidgetElement() {
+  defineLive2dElement();
+  if (widgetDefined) return;
+  if (typeof customElements === "undefined") return;
+  if (customElements.get(LIVE2D_WIDGET_ELEMENT_TAG)) {
+    widgetDefined = true;
+    return;
+  }
+  customElements.define(LIVE2D_WIDGET_ELEMENT_TAG, Live2dWidgetElement);
+  widgetDefined = true;
+}
+function defineLive2dElements() {
+  defineLive2dElement();
+  defineLive2dWidgetElement();
 }
 
 // src/index.ts
-defineLive2dElement();
+defineLive2dElements();
 export {
   LIVE2D_ELEMENT_TAG,
+  LIVE2D_WIDGET_ELEMENT_TAG,
   Live2dElement,
-  defineLive2dElement
+  Live2dWidgetElement,
+  defineLive2dElement,
+  defineLive2dElements,
+  defineLive2dWidgetElement
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doki-land/live2d-element",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "description": "Official <live-2d> Custom Element — thin host over @doki-land/live2d (Stage-owned RAF).",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@doki-land/live2d": "0.0.23"
+    "@doki-land/live2d": "0.0.24"
   },
   "sideEffects": [
     "./src/index.ts",

package/src/define.ts

@@ -1,15 +1,39 @@
 import { LIVE2D_ELEMENT_TAG, Live2dElement } from "./live2d-element.js";
+import {
+    LIVE2D_WIDGET_ELEMENT_TAG,
+    Live2dWidgetElement,
+} from "./live2d-widget-element.js";
 
-let defined = false;
+let elementDefined = false;
+let widgetDefined = false;
 
 /** Idempotent `customElements.define('live-2d', …)`. */
 export function defineLive2dElement(): void {
-    if (defined) return;
+    if (elementDefined) return;
     if (typeof customElements === "undefined") return;
     if (customElements.get(LIVE2D_ELEMENT_TAG)) {
-        defined = true;
+        elementDefined = true;
         return;
     }
     customElements.define(LIVE2D_ELEMENT_TAG, Live2dElement);
-    defined = true;
+    elementDefined = true;
+}
+
+/** Idempotent `customElements.define('live-2d-widget', …)`. */
+export function defineLive2dWidgetElement(): void {
+    defineLive2dElement();
+    if (widgetDefined) return;
+    if (typeof customElements === "undefined") return;
+    if (customElements.get(LIVE2D_WIDGET_ELEMENT_TAG)) {
+        widgetDefined = true;
+        return;
+    }
+    customElements.define(LIVE2D_WIDGET_ELEMENT_TAG, Live2dWidgetElement);
+    widgetDefined = true;
+}
+
+/** Register both official CE tags. */
+export function defineLive2dElements(): void {
+    defineLive2dElement();
+    defineLive2dWidgetElement();
 }

package/src/index.ts

@@ -1,21 +1,28 @@
 /**
- * `@doki-land/live2d-element` — official `<live-2d>` Custom Element.
+ * `@doki-land/live2d-element` — official `<live-2d>` / `<live-2d-widget>` CEs.
  *
- * v0.0.22 thin gate: pure TypeScript CE wrapping `@doki-land/live2d`
- * (`createLive2D` + Stage-owned RAF). Zero VMZ runtime dependency.
- * Design `01` still targets eventual `vmz build --target custom-element`
- * when that CLI target ships in published `@vmz/vmz`; until then this
- * package is the cross-ecosystem ABI skeleton.
+ * Pure TypeScript CE wrapping `@doki-land/live2d` (`createLive2d` + Stage-owned
+ * RAF). Zero VMZ runtime dependency. Design `01` still targets eventual
+ * `vmz build --target custom-element` when that CLI target ships.
  */
 
-export { defineLive2dElement } from "./define.js";
+export {
+    defineLive2dElement,
+    defineLive2dElements,
+    defineLive2dWidgetElement,
+} from "./define.js";
 export {
     LIVE2D_ELEMENT_TAG,
     Live2dElement,
     type Live2dElementRenderer,
+    type Live2dElementTracking,
 } from "./live2d-element.js";
+export {
+    LIVE2D_WIDGET_ELEMENT_TAG,
+    Live2dWidgetElement,
+} from "./live2d-widget-element.js";
 
-import { defineLive2dElement } from "./define.js";
+import { defineLive2dElements } from "./define.js";
 
 /** Side-effect registration for `<script type="module">` consumers. */
-defineLive2dElement();
+defineLive2dElements();

package/src/live2d-element.ts

@@ -1,10 +1,23 @@
-import { createLive2D, type Live2DRuntime } from "@doki-land/live2d";
+import {
+    createLive2d,
+    type Live2dRuntime,
+    type PlayMotionOptions,
+} from "@doki-land/live2d";
 
 export const LIVE2D_ELEMENT_TAG = "live-2d" as const;
 
 export type Live2dElementRenderer = "auto" | "webgpu" | "webgl2" | "canvas2d";
+export type Live2dElementTracking = "pointer" | "none";
 
-const OBSERVED = ["model", "renderer", "width", "height", "autoplay"] as const;
+const OBSERVED = [
+    "model",
+    "renderer",
+    "width",
+    "height",
+    "autoplay",
+    "interactive",
+    "tracking",
+] as const;
 
 function preferFromRenderer(
     renderer: Live2dElementRenderer,
@@ -28,14 +41,14 @@ function parseBoolAttr(
 }
 
 /**
- * Thin `<live-2d>` host: attribute → createLive2D → Stage RAF → live2d-* events.
+ * Thin `<live-2d>` host: attribute → createLive2d → Stage RAF → live2d-* events.
  */
 export class Live2dElement extends HTMLElement {
     static get observedAttributes(): string[] {
         return [...OBSERVED];
     }
 
-    #runtime: Live2DRuntime | null = null;
+    #runtime: Live2dRuntime | null = null;
     #canvas: HTMLCanvasElement | null = null;
     #mountGen = 0;
     #model = "";
@@ -43,7 +56,11 @@ export class Live2dElement extends HTMLElement {
     #width = 320;
     #height = 320;
     #autoplay = true;
+    #interactive = false;
+    #tracking: Live2dElementTracking = "none";
     #connected = false;
+    #boundPointer: ((event: PointerEvent) => void) | null = null;
+    #unsubs: Array<() => void> = [];
 
     get model(): string {
         return this.#model;
@@ -83,16 +100,71 @@ export class Live2dElement extends HTMLElement {
         else this.removeAttribute("autoplay");
     }
 
-    get runtime(): Live2DRuntime | null {
+    get interactive(): boolean {
+        return this.#interactive;
+    }
+    set interactive(value: boolean) {
+        if (value) this.setAttribute("interactive", "");
+        else this.removeAttribute("interactive");
+    }
+
+    get tracking(): Live2dElementTracking {
+        return this.#tracking;
+    }
+    set tracking(value: Live2dElementTracking) {
+        this.setAttribute("tracking", value === "pointer" ? "pointer" : "none");
+    }
+
+    get runtime(): Live2dRuntime | null {
         return this.#runtime;
     }
 
     /** Imperative reload (also used when `model` attribute changes). */
-    async loadModel(source?: string): Promise<void> {
+    async loadModel(
+        source?: string,
+        opts?: { signal?: AbortSignal },
+    ): Promise<void> {
         if (source !== undefined) {
             this.model = String(source);
         }
-        await this.#boot();
+        await this.#boot(opts?.signal);
+    }
+
+    playMotion(
+        group: string,
+        index?: number,
+        options?: PlayMotionOptions,
+    ): Promise<boolean> {
+        return (
+            this.#runtime?.playMotion(group, index, options) ??
+            Promise.resolve(false)
+        );
+    }
+
+    setExpression(name: string | null): Promise<boolean> {
+        return this.#runtime?.setExpression(name) ?? Promise.resolve(false);
+    }
+
+    /** Stage-normalized look-at in [-1, 1] client-mapped coords (x right, y up). */
+    lookAt(x: number, y: number): void {
+        const stageX = (Number(x) + 1) / 2;
+        const stageY = (1 - Number(y)) / 2;
+        this.#runtime?.actor.lookAt(stageX, stageY);
+    }
+
+    pause(): void {
+        this.#runtime?.stage.pause();
+    }
+
+    resume(): void {
+        this.#runtime?.stage.resume();
+        if (this.#autoplay) {
+            try {
+                this.#runtime?.stage.start();
+            } catch {
+                /* already running */
+            }
+        }
     }
 
     connectedCallback(): void {
@@ -139,6 +211,16 @@ export class Live2dElement extends HTMLElement {
                 if (this.#autoplay) this.#runtime.stage.start();
                 else this.#runtime.stage.pause();
             }
+            return;
+        }
+        if (name === "interactive") {
+            this.#interactive = parseBoolAttr(this, "interactive", false);
+            this.#syncPointer();
+            return;
+        }
+        if (name === "tracking") {
+            this.#tracking = value === "pointer" ? "pointer" : "none";
+            this.#syncPointer();
         }
     }
 
@@ -163,6 +245,9 @@ export class Live2dElement extends HTMLElement {
             );
         }
         this.#autoplay = parseBoolAttr(this, "autoplay", true);
+        this.#interactive = parseBoolAttr(this, "interactive", false);
+        this.#tracking =
+            this.getAttribute("tracking") === "pointer" ? "pointer" : "none";
     }
 
     #ensureCanvas(): HTMLCanvasElement {
@@ -191,7 +276,67 @@ export class Live2dElement extends HTMLElement {
         this.#runtime?.stage.resize?.(this.#width, this.#height);
     }
 
+    #clearUnsubs(): void {
+        for (const off of this.#unsubs) {
+            try {
+                off();
+            } catch {
+                /* ignore */
+            }
+        }
+        this.#unsubs = [];
+    }
+
+    #detachPointer(): void {
+        if (this.#canvas && this.#boundPointer) {
+            this.#canvas.removeEventListener("pointerdown", this.#boundPointer);
+            this.#canvas.removeEventListener("pointermove", this.#boundPointer);
+        }
+        this.#boundPointer = null;
+    }
+
+    #syncPointer(): void {
+        this.#detachPointer();
+        const canvas = this.#canvas;
+        const runtime = this.#runtime;
+        if (!canvas || !runtime) return;
+        if (!this.#interactive && this.#tracking !== "pointer") return;
+
+        this.#boundPointer = (event: PointerEvent) => {
+            const rect = canvas.getBoundingClientRect();
+            if (rect.width <= 0 || rect.height <= 0) return;
+            const nx = ((event.clientX - rect.left) / rect.width) * 2 - 1;
+            const ny = 1 - ((event.clientY - rect.top) / rect.height) * 2;
+            if (this.#tracking === "pointer" || event.type === "pointermove") {
+                this.lookAt(nx, ny);
+            }
+            if (this.#interactive && event.type === "pointerdown") {
+                const area = runtime.hitTest(nx, ny);
+                this.dispatchEvent(
+                    new CustomEvent("live2d-hit", {
+                        bubbles: true,
+                        composed: true,
+                        detail: {
+                            area,
+                            modelX: nx,
+                            modelY: ny,
+                            originalEvent: event,
+                        },
+                    }),
+                );
+            }
+        };
+        if (this.#interactive) {
+            canvas.addEventListener("pointerdown", this.#boundPointer);
+        }
+        if (this.#tracking === "pointer") {
+            canvas.addEventListener("pointermove", this.#boundPointer);
+        }
+    }
+
     #destroyRuntime(): void {
+        this.#clearUnsubs();
+        this.#detachPointer();
         try {
             this.#runtime?.stage.stop?.();
         } catch {
@@ -203,7 +348,7 @@ export class Live2dElement extends HTMLElement {
         this.removeAttribute("aria-busy");
     }
 
-    async #boot(): Promise<void> {
+    async #boot(signal?: AbortSignal): Promise<void> {
         if (!this.#connected) return;
         const model = this.#model.trim();
         if (!model) return;
@@ -211,12 +356,23 @@ export class Live2dElement extends HTMLElement {
         const gen = ++this.#mountGen;
         this.#destroyRuntime();
 
+        if (signal?.aborted) {
+            this.#emitError(signal.reason ?? new Error("aborted"));
+            return;
+        }
+
+        const onAbort = () => {
+            this.#mountGen += 1;
+            this.#destroyRuntime();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+
         const canvas = this.#ensureCanvas();
         this.setAttribute("data-phase", "loading");
         this.setAttribute("aria-busy", "true");
 
         try {
-            const runtime = createLive2D({
+            const runtime = createLive2d({
                 prefer: preferFromRenderer(this.#renderer),
                 updateMode: "auto",
             });
@@ -225,41 +381,75 @@ export class Live2dElement extends HTMLElement {
                 return;
             }
 
-            runtime.events.on("ready", () => {
-                if (gen !== this.#mountGen) return;
-                this.setAttribute("data-phase", "live");
-                this.setAttribute("aria-busy", "false");
-                if (this.#autoplay) {
-                    try {
-                        runtime.stage.start();
-                    } catch {
-                        /* already running */
+            this.#unsubs.push(
+                runtime.events.on("ready", () => {
+                    if (gen !== this.#mountGen) return;
+                    this.setAttribute("data-phase", "live");
+                    this.setAttribute("aria-busy", "false");
+                    if (this.#autoplay) {
+                        try {
+                            runtime.stage.start();
+                        } catch {
+                            /* already running */
+                        }
                     }
-                }
-                this.dispatchEvent(
-                    new CustomEvent("live2d-ready", {
-                        bubbles: true,
-                        composed: true,
-                        detail: { model },
-                    }),
-                );
-            });
+                    this.#syncPointer();
+                    this.dispatchEvent(
+                        new CustomEvent("live2d-ready", {
+                            bubbles: true,
+                            composed: true,
+                            detail: { model },
+                        }),
+                    );
+                }),
+            );
 
-            runtime.events.on("error", (payload) => {
-                if (gen !== this.#mountGen) return;
-                this.#emitError(payload?.error ?? "load error");
-            });
+            this.#unsubs.push(
+                runtime.events.on("error", (payload) => {
+                    if (gen !== this.#mountGen) return;
+                    this.#emitError(payload?.error ?? "load error");
+                }),
+            );
+
+            this.#unsubs.push(
+                runtime.events.on("motion:start", (payload) => {
+                    if (gen !== this.#mountGen) return;
+                    this.dispatchEvent(
+                        new CustomEvent("live2d-motion-start", {
+                            bubbles: true,
+                            composed: true,
+                            detail: payload,
+                        }),
+                    );
+                }),
+            );
+
+            this.#unsubs.push(
+                runtime.events.on("motion:finish", (payload) => {
+                    if (gen !== this.#mountGen) return;
+                    this.dispatchEvent(
+                        new CustomEvent("live2d-motion-finish", {
+                            bubbles: true,
+                            composed: true,
+                            detail: payload,
+                        }),
+                    );
+                }),
+            );
 
             runtime.mount(canvas);
-            await runtime.loadModel(model);
+            await runtime.loadModel(model, undefined, { signal });
             if (gen !== this.#mountGen) {
                 runtime.destroy();
                 return;
             }
             this.#runtime = runtime;
+            this.#syncPointer();
         } catch (err) {
             if (gen !== this.#mountGen) return;
             this.#emitError(err);
+        } finally {
+            signal?.removeEventListener("abort", onAbort);
         }
     }
 

package/src/live2d-widget-element.ts

@@ -0,0 +1,117 @@
+import { defineLive2dElement } from "./define.js";
+import { LIVE2D_ELEMENT_TAG, type Live2dElement } from "./live2d-element.js";
+
+export const LIVE2D_WIDGET_ELEMENT_TAG = "live-2d-widget" as const;
+
+const OBSERVED = ["model", "renderer", "width", "height", "autoplay"] as const;
+
+/**
+ * Thin `<live-2d-widget>` product-shell CE (v0.0.24 POC).
+ *
+ * Owns chrome layout only; delegates model/RAF/hit to an inner `<live-2d>`.
+ * Does not create a second Stage clock.
+ */
+export class Live2dWidgetElement extends HTMLElement {
+    static get observedAttributes(): string[] {
+        return [...OBSERVED];
+    }
+
+    #host: HTMLElement | null = null;
+    #actor: Live2dElement | null = null;
+
+    get model(): string {
+        return this.getAttribute("model") ?? "";
+    }
+    set model(value: string) {
+        const next = String(value ?? "");
+        if (next) this.setAttribute("model", next);
+        else this.removeAttribute("model");
+    }
+
+    get renderer(): string {
+        return this.getAttribute("renderer") ?? "auto";
+    }
+    set renderer(value: string) {
+        this.setAttribute("renderer", value || "auto");
+    }
+
+    get width(): number {
+        return Math.max(1, Number(this.getAttribute("width")) || 320);
+    }
+    set width(value: number) {
+        this.setAttribute("width", String(Math.max(1, Number(value) || 320)));
+    }
+
+    get height(): number {
+        return Math.max(1, Number(this.getAttribute("height")) || 320);
+    }
+    set height(value: number) {
+        this.setAttribute("height", String(Math.max(1, Number(value) || 320)));
+    }
+
+    get autoplay(): boolean {
+        if (!this.hasAttribute("autoplay")) return true;
+        const v = this.getAttribute("autoplay");
+        if (v === null || v === "" || v === "autoplay") return true;
+        return v !== "false" && v !== "0";
+    }
+    set autoplay(value: boolean) {
+        if (value) this.setAttribute("autoplay", "");
+        else this.removeAttribute("autoplay");
+    }
+
+    /** Inner `<live-2d>` when present. */
+    get actor(): Live2dElement | null {
+        return this.#actor;
+    }
+
+    connectedCallback(): void {
+        defineLive2dElement();
+        this.#ensureDom();
+        this.#syncActorFromAttributes();
+    }
+
+    attributeChangedCallback(): void {
+        if (!this.isConnected) return;
+        this.#syncActorFromAttributes();
+    }
+
+    #ensureDom(): void {
+        if (this.#host?.isConnected) return;
+
+        let actor = this.querySelector(
+            LIVE2D_ELEMENT_TAG,
+        ) as Live2dElement | null;
+        if (!actor) {
+            actor = document.createElement(LIVE2D_ELEMENT_TAG) as Live2dElement;
+        } else {
+            actor.remove();
+        }
+
+        this.replaceChildren();
+        const host = document.createElement("div");
+        host.setAttribute("part", "chrome");
+        host.className = "live2d-widget-chrome";
+        host.appendChild(actor);
+        this.appendChild(host);
+        this.#host = host;
+        this.#actor = actor;
+    }
+
+    #syncActorFromAttributes(): void {
+        this.#ensureDom();
+        const actor = this.#actor;
+        if (!actor) return;
+
+        if (this.hasAttribute("model")) {
+            actor.setAttribute("model", this.model);
+        }
+        if (this.hasAttribute("renderer")) {
+            actor.setAttribute("renderer", this.renderer);
+        }
+        actor.setAttribute("width", String(this.width));
+        actor.setAttribute("height", String(this.height));
+        if (this.autoplay) actor.setAttribute("autoplay", "");
+        else actor.removeAttribute("autoplay");
+    }
+}