@doki-land/live2d-widget 0.0.22 → 0.0.24

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CreateLive2DOptions, Live2DRuntime } from '@doki-land/live2d';
+import { Live2dStage, Live2dActor, RendererKind, Live2DRuntime } from '@doki-land/live2d';
 
 /**
  * Optional page chrome for `@doki-land/live2d-widget`:
@@ -40,42 +40,68 @@ declare function mountChrome(options: {
     getCanvas: () => HTMLCanvasElement | null;
 }): ChromeSession | null;
 
-interface WidgetOptions extends CreateLive2DOptions {
-    /** CSS selector or element to host the canvas. */
+/** Composed widget over an existing Stage + Actor (no second RAF). */
+interface ComposedWidgetOptions {
+    target: string | HTMLElement;
+    stage: Live2dStage;
+    actor: Live2dActor;
+    width?: number;
+    height?: number;
+    /** Drive PARAM_ANGLE_X with a sine while the stage loop runs. Default true. */
+    autoSway?: boolean;
+    /** Start Stage-owned RAF after mount. Default true. */
+    autoplay?: boolean;
+    chrome?: boolean | WidgetChromeOptions;
+    onHit?: (payload: {
+        area: string;
+        x: number;
+        y: number;
+    }) => void;
+}
+/**
+ * Legacy bootstrap that still creates its own Stage + Actor.
+ * Prefer composing `stage` + `actor` yourself and calling `createLive2dWidget`.
+ */
+interface LegacyWidgetOptions {
     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. */
+    prefer?: RendererKind[];
     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;
 }
+type WidgetOptions = ComposedWidgetOptions | LegacyWidgetOptions;
 /**
- * Page widget shell over `@doki-land/live2d`.
- * Renderer fallback is `createRenderer({ prefer })` (webgpu → webgl2 → canvas2d).
+ * Page widget shell — product chrome over Stage + Actor.
+ * Does not own renderer selection or a private RAF loop.
  */
-declare class Live2DWidget {
+declare class Live2dWidget {
     #private;
     mount(options: WidgetOptions): Promise<void>;
     destroy(): void;
+    get stage(): Live2dStage | null;
+    get actor(): Live2dActor | null;
+    /** Legacy accessor when mounted via `createLive2D`. */
     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>;
+/** @deprecated Use `Live2dWidget` — alias kept for hexo / legacy imports. */
+declare const Live2DWidget: typeof Live2dWidget;
+declare function createLive2dWidget(options: ComposedWidgetOptions): Promise<Live2dWidget>;
+declare function mountWidget(options: WidgetOptions): Promise<Live2dWidget>;
+/** Convenience bootstrap: Stage + default Actor + widget chrome. */
+declare function mountWidgetWithStage(options: LegacyWidgetOptions): Promise<{
+    widget: Live2dWidget;
+    stage: Live2dStage;
+    actor: Live2dActor;
+}>;
 
 /**
  * `@doki-land/live2d-widget` — browser embed helper.
@@ -83,4 +109,4 @@ declare function mountWidget(options: WidgetOptions): Promise<Live2DWidget>;
 
 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 };
+export { type ComposedWidgetOptions, DEFAULT_WELCOME, LIVE2D_WIDGET_VERSION, type LegacyWidgetOptions, Live2DWidget, Live2dWidget, type WidgetChromeOptions, type WidgetOptions, type WidgetToolId, createLive2dWidget, createTipMessage, ensureChromeStyles, mountChrome, mountWidget, mountWidgetWithStage };

package/dist/index.js

@@ -222,16 +222,24 @@ function mountChrome(options) {
 
 // src/shell/widget.ts
 import {
+  allocateActorId,
   createLive2D,
+  createLive2dStage,
+  createRenderer,
   focusParameterUpdates
 } from "@doki-land/live2d";
-var Live2DWidget = class {
+function isLegacyOptions(options) {
+  return !("stage" in options && "actor" in options);
+}
+var Live2dWidget = class {
   #canvas = null;
+  #stage = null;
+  #actor = null;
   #runtime = null;
   #chrome = null;
-  #raf = 0;
-  #lastTs = 0;
+  #unsubFrame = null;
   #autoSway = true;
+  #swayPhase = 0;
   #onHit;
   async mount(options) {
     const host = typeof options.target === "string" ? document.querySelector(options.target) : options.target;
@@ -249,15 +257,29 @@ var Live2DWidget = class {
     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);
+    let stage;
+    let actor;
+    if (isLegacyOptions(options)) {
+      const prefer = normalizePrefer(options.prefer);
+      const runtime = createLive2D({
+        prefer,
+        updateMode: "auto"
+      });
+      await runtime.mount(canvas);
+      if (options.model) {
+        await runtime.loadModel(options.model);
+      }
+      this.#runtime = runtime;
+      stage = runtime.stage;
+      actor = runtime.actor;
+    } else {
+      stage = options.stage;
+      actor = options.actor;
+      await stage.mount(canvas);
+    }
     this.#canvas = canvas;
-    this.#runtime = runtime;
+    this.#stage = stage;
+    this.#actor = actor;
     this.#autoSway = options.autoSway !== false;
     this.#onHit = options.onHit;
     this.#chrome = mountChrome({
@@ -269,17 +291,26 @@ var Live2DWidget = class {
     if (!this.#chrome) {
       host.replaceChildren(canvas);
     }
-    if (options.model) {
-      await runtime.loadModel(options.model);
+    if (this.#autoSway) {
+      this.#unsubFrame = stage.onFrame((dt) => {
+        this.#swayPhase += dt;
+        const binding = actor.parameterMap().get("PARAM_ANGLE_X");
+        if (!binding) return;
+        const normalized = Math.sin(this.#swayPhase) * 0.25;
+        const value = normalized >= 0 ? binding.defaultValue + (binding.max - binding.defaultValue) * normalized : binding.defaultValue + (binding.defaultValue - binding.min) * normalized;
+        actor.setParameter("PARAM_ANGLE_X", value);
+      });
     }
     if (options.autoplay !== false) {
-      this.#startLoop();
+      stage.start();
     } else {
-      runtime.update(0);
+      stage.update(0);
+      stage.render();
     }
   }
   destroy() {
-    this.#stopLoop();
+    this.#unsubFrame?.();
+    this.#unsubFrame = null;
     if (this.#canvas) {
       this.#canvas.removeEventListener(
         "pointermove",
@@ -292,24 +323,31 @@ var Live2DWidget = class {
     }
     this.#chrome?.destroy();
     this.#chrome = null;
-    this.#runtime?.destroy();
+    if (this.#runtime) {
+      this.#runtime.destroy();
+    } else {
+      this.#stage?.stop();
+    }
     this.#canvas?.remove();
-    this.#runtime = null;
     this.#canvas = null;
+    this.#stage = null;
+    this.#actor = null;
+    this.#runtime = null;
     this.#onHit = void 0;
   }
+  get stage() {
+    return this.#stage;
+  }
+  get actor() {
+    return this.#actor;
+  }
+  /** Legacy accessor when mounted via `createLive2D`. */
   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?.parameterMap().get(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;
@@ -322,69 +360,60 @@ var Live2DWidget = class {
   }
   #onPointerMove = (event) => {
     const p = this.#modelPoint(event);
-    const runtime = this.#runtime;
-    if (!p || !runtime) return;
-    this.#autoSwayPausedByPointer = true;
+    const actor = this.#actor;
+    if (!p || !actor) return;
     for (const { id, value } of focusParameterUpdates(
-      runtime.parameterMap(),
+      actor.parameterMap(),
       p.x,
       p.y
     )) {
-      runtime.setParameter(id, value);
+      actor.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);
-    }
+    const stage = this.#stage;
+    const actor = this.#actor;
+    if (!p || !stage || !actor) return;
+    const stageX = (p.x + 1) / 2;
+    const stageY = (1 - p.y) / 2;
+    const hit = stage.hitTest(stageX, stageY);
+    if (!hit || hit.actorId !== actor.id) return;
+    this.#onHit?.({ area: hit.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;
-  }
 };
+var Live2DWidget = Live2dWidget;
 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 createLive2dWidget(options) {
+  const widget = new Live2dWidget();
+  await widget.mount(options);
+  return widget;
+}
 async function mountWidget(options) {
-  const widget = new Live2DWidget();
+  const widget = new Live2dWidget();
   await widget.mount(options);
   return widget;
 }
+async function mountWidgetWithStage(options) {
+  const prefer = normalizePrefer(options.prefer);
+  const stage = createLive2dStage({
+    renderer: createRenderer({ prefer }),
+    updateMode: "auto"
+  });
+  const actor = stage.createActor({ id: allocateActorId("widget") });
+  const widget = new Live2dWidget();
+  await widget.mount({ ...options, stage, actor });
+  if (options.model) {
+    await actor.load(options.model);
+  }
+  return { widget, stage, actor };
+}
 
 // src/index.ts
 var LIVE2D_WIDGET_VERSION = "0.0.0";
@@ -392,8 +421,11 @@ export {
   DEFAULT_WELCOME,
   LIVE2D_WIDGET_VERSION,
   Live2DWidget,
+  Live2dWidget,
+  createLive2dWidget,
   createTipMessage,
   ensureChromeStyles,
   mountChrome,
-  mountWidget
+  mountWidget,
+  mountWidgetWithStage
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@doki-land/live2d-widget",
-  "version": "0.0.22",
-  "description": "Live2D page widget — canvas shell, autoplay, optional tips chrome; built on @doki-land/live2d.",
+  "version": "0.0.24",
+  "description": "Live2D page widget — product chrome over Stage + Actor (no private RAF); built on @doki-land/live2d.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/doki-land/live2d.ts",
@@ -39,10 +39,10 @@
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run"
   },
   "dependencies": {
-    "@doki-land/live2d": "0.0.22"
+    "@doki-land/live2d": "0.0.24"
   },
   "sideEffects": false
 }

package/src/index.ts

@@ -9,8 +9,14 @@ export {
     mountChrome,
 } from "./chrome/chrome.js";
 export {
+    type ComposedWidgetOptions,
+    createLive2dWidget,
+    type LegacyWidgetOptions,
+    /** @deprecated Use `Live2dWidget`. */
     Live2DWidget,
+    Live2dWidget,
     mountWidget,
+    mountWidgetWithStage,
     type WidgetChromeOptions,
     type WidgetOptions,
     type WidgetToolId,

package/src/shell/widget.ts

@@ -1,8 +1,12 @@
 import {
-    type CreateLive2DOptions,
+    allocateActorId,
     createLive2D,
+    createLive2dStage,
+    createRenderer,
     focusParameterUpdates,
     type Live2DRuntime,
+    type Live2dActor,
+    type Live2dStage,
     type RendererKind,
 } from "@doki-land/live2d";
 import {
@@ -13,38 +17,59 @@ import {
 
 export type { WidgetChromeOptions, WidgetToolId } from "../chrome/chrome.js";
 
-export interface WidgetOptions extends CreateLive2DOptions {
-    /** CSS selector or element to host the canvas. */
+/** Composed widget over an existing Stage + Actor (no second RAF). */
+export interface ComposedWidgetOptions {
+    target: string | HTMLElement;
+    stage: Live2dStage;
+    actor: Live2dActor;
+    width?: number;
+    height?: number;
+    /** Drive PARAM_ANGLE_X with a sine while the stage loop runs. Default true. */
+    autoSway?: boolean;
+    /** Start Stage-owned RAF after mount. Default true. */
+    autoplay?: boolean;
+    chrome?: boolean | WidgetChromeOptions;
+    onHit?: (payload: { area: string; x: number; y: number }) => void;
+}
+
+/**
+ * Legacy bootstrap that still creates its own Stage + Actor.
+ * Prefer composing `stage` + `actor` yourself and calling `createLive2dWidget`.
+ */
+export interface LegacyWidgetOptions {
     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. */
+    prefer?: RendererKind[];
     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;
 }
 
+export type WidgetOptions = ComposedWidgetOptions | LegacyWidgetOptions;
+
+function isLegacyOptions(
+    options: WidgetOptions,
+): options is LegacyWidgetOptions {
+    return !("stage" in options && "actor" in options);
+}
+
 /**
- * Page widget shell over `@doki-land/live2d`.
- * Renderer fallback is `createRenderer({ prefer })` (webgpu → webgl2 → canvas2d).
+ * Page widget shell — product chrome over Stage + Actor.
+ * Does not own renderer selection or a private RAF loop.
  */
-export class Live2DWidget {
+export class Live2dWidget {
     #canvas: HTMLCanvasElement | null = null;
+    #stage: Live2dStage | null = null;
+    #actor: Live2dActor | null = null;
     #runtime: Live2DRuntime | null = null;
     #chrome: ChromeSession | null = null;
-    #raf = 0;
-    #lastTs = 0;
+    #unsubFrame: (() => void) | null = null;
     #autoSway = true;
-    #onHit: WidgetOptions["onHit"];
+    #swayPhase = 0;
+    #onHit: ComposedWidgetOptions["onHit"];
 
     async mount(options: WidgetOptions): Promise<void> {
         const host =
@@ -69,16 +94,30 @@ export class Live2DWidget {
         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);
+        let stage: Live2dStage;
+        let actor: Live2dActor;
+        if (isLegacyOptions(options)) {
+            const prefer = normalizePrefer(options.prefer);
+            const runtime = createLive2D({
+                prefer,
+                updateMode: "auto",
+            });
+            await runtime.mount(canvas);
+            if (options.model) {
+                await runtime.loadModel(options.model);
+            }
+            this.#runtime = runtime;
+            stage = runtime.stage;
+            actor = runtime.actor;
+        } else {
+            stage = options.stage;
+            actor = options.actor;
+            await stage.mount(canvas);
+        }
 
         this.#canvas = canvas;
-        this.#runtime = runtime;
+        this.#stage = stage;
+        this.#actor = actor;
         this.#autoSway = options.autoSway !== false;
         this.#onHit = options.onHit;
         this.#chrome = mountChrome({
@@ -91,19 +130,33 @@ export class Live2DWidget {
             host.replaceChildren(canvas);
         }
 
-        if (options.model) {
-            await runtime.loadModel(options.model);
+        if (this.#autoSway) {
+            this.#unsubFrame = stage.onFrame((dt) => {
+                this.#swayPhase += dt;
+                const binding = actor.parameterMap().get("PARAM_ANGLE_X");
+                if (!binding) return;
+                const normalized = Math.sin(this.#swayPhase) * 0.25;
+                const value =
+                    normalized >= 0
+                        ? binding.defaultValue +
+                          (binding.max - binding.defaultValue) * normalized
+                        : binding.defaultValue +
+                          (binding.defaultValue - binding.min) * normalized;
+                actor.setParameter("PARAM_ANGLE_X", value);
+            });
         }
 
         if (options.autoplay !== false) {
-            this.#startLoop();
+            stage.start();
         } else {
-            runtime.update(0);
+            stage.update(0);
+            stage.render();
         }
     }
 
     destroy(): void {
-        this.#stopLoop();
+        this.#unsubFrame?.();
+        this.#unsubFrame = null;
         if (this.#canvas) {
             this.#canvas.removeEventListener(
                 "pointermove",
@@ -116,18 +169,32 @@ export class Live2DWidget {
         }
         this.#chrome?.destroy();
         this.#chrome = null;
-        this.#runtime?.destroy();
+        if (this.#runtime) {
+            this.#runtime.destroy();
+        } else {
+            this.#stage?.stop();
+        }
         this.#canvas?.remove();
-        this.#runtime = null;
         this.#canvas = null;
+        this.#stage = null;
+        this.#actor = null;
+        this.#runtime = null;
         this.#onHit = undefined;
     }
 
+    get stage(): Live2dStage | null {
+        return this.#stage;
+    }
+
+    get actor(): Live2dActor | null {
+        return this.#actor;
+    }
+
+    /** Legacy accessor when mounted via `createLive2D`. */
     getRuntime(): Live2DRuntime | null {
         return this.#runtime;
     }
 
-    /** Show a tips bubble when chrome tips are enabled. */
     showMessage(
         text: string | string[],
         timeoutMs?: number,
@@ -136,16 +203,6 @@ export class Live2DWidget {
         this.#chrome?.tips?.show(text, timeoutMs, priority);
     }
 
-    #parameterFromNormalized(id: string, normalized: number): number {
-        const binding = this.#runtime?.parameterMap().get(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;
@@ -159,65 +216,34 @@ export class Live2DWidget {
 
     #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;
+        const actor = this.#actor;
+        if (!p || !actor) return;
         for (const { id, value } of focusParameterUpdates(
-            runtime.parameterMap(),
+            actor.parameterMap(),
             p.x,
             p.y,
         )) {
-            runtime.setParameter(id, value);
+            actor.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);
-        }
+        const stage = this.#stage;
+        const actor = this.#actor;
+        if (!p || !stage || !actor) return;
+        const stageX = (p.x + 1) / 2;
+        const stageY = (1 - p.y) / 2;
+        const hit = stage.hitTest(stageX, stageY);
+        if (!hit || hit.actorId !== actor.id) return;
+        this.#onHit?.({ area: hit.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;
-    }
 }
 
+/** @deprecated Use `Live2dWidget` — alias kept for hexo / legacy imports. */
+export const Live2DWidget = Live2dWidget;
+
 function normalizePrefer(
     prefer: RendererKind[] | undefined,
 ): RendererKind[] | undefined {
@@ -227,10 +253,36 @@ function normalizePrefer(
     return out.length ? out : undefined;
 }
 
+export async function createLive2dWidget(
+    options: ComposedWidgetOptions,
+): Promise<Live2dWidget> {
+    const widget = new Live2dWidget();
+    await widget.mount(options);
+    return widget;
+}
+
 export async function mountWidget(
     options: WidgetOptions,
-): Promise<Live2DWidget> {
-    const widget = new Live2DWidget();
+): Promise<Live2dWidget> {
+    const widget = new Live2dWidget();
     await widget.mount(options);
     return widget;
 }
+
+/** Convenience bootstrap: Stage + default Actor + widget chrome. */
+export async function mountWidgetWithStage(
+    options: LegacyWidgetOptions,
+): Promise<{ widget: Live2dWidget; stage: Live2dStage; actor: Live2dActor }> {
+    const prefer = normalizePrefer(options.prefer);
+    const stage = createLive2dStage({
+        renderer: createRenderer({ prefer }),
+        updateMode: "auto",
+    });
+    const actor = stage.createActor({ id: allocateActorId("widget") });
+    const widget = new Live2dWidget();
+    await widget.mount({ ...options, stage, actor });
+    if (options.model) {
+        await actor.load(options.model);
+    }
+    return { widget, stage, actor };
+}