@doki-land/live2d 0.0.23 → 0.0.24

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _doki_land_live2d_core from '@doki-land/live2d-core';
-import { Live2dStageAssets, ModelSource, AssetResolver, ModelAsset, LoadProgress, ModelSettings, InternalModel, Live2dActor, CreateActorOptions, ActorTransform, PlayMotionActorOptions, ActorHit, CreateLive2dStageOptions, Live2dStage, PointerTrackingPolicy, StagePointerEvent, Live2DSession, HitAreaDefinition } from '@doki-land/live2d-core';
-export { ActorHit, ActorInstance, ActorTransform, AssetResolver, CreateActorOptions, CreateLive2dStageOptions, DEFAULT_ACTOR_TRANSFORM, EventEmitter, FrameProfile, FrameSnapshot, InternalModel, Live2DSession, Live2dActor, Live2dStage, Live2dStageAssets, LoadProgress, LoadProgressStage, ModelAsset, ModelFormat, ModelInstance, ModelProgram, ModelSettings, ModelSource, PlayMotionActorOptions, PointerTrackingMode, PointerTrackingPolicy, SessionPhase, SessionState, StagePointerEvent, StageUpdateMode } from '@doki-land/live2d-core';
+import { Live2dStageAssets, ModelSource, AssetResolver, ModelAsset, LoadProgress, ModelSettings, InternalModel, Live2dActor, CreateActorOptions, ActorTransform, PlayMotionActorOptions, ActorHit, CreateLive2dStageOptions, Live2dStage, PointerTrackingPolicy, StagePointerEvent, Live2dSession, HitAreaDefinition } from '@doki-land/live2d-core';
+export { ActorHit, ActorInstance, ActorTransform, AssetResolver, CreateActorOptions, CreateLive2dStageOptions, DEFAULT_ACTOR_TRANSFORM, EventEmitter, FrameProfile, FrameSnapshot, InternalModel, Live2dActor, Live2dSession, Live2dStage, Live2dStageAssets, LoadProgress, LoadProgressStage, ModelAsset, ModelFormat, ModelInstance, ModelProgram, ModelSettings, ModelSource, PlayMotionActorOptions, PointerTrackingMode, PointerTrackingPolicy, SessionPhase, SessionState, StagePointerEvent, StageUpdateMode } from '@doki-land/live2d-core';
 export { DEFAULT_NPM_CDN, resolveModelSourceUrl, resolveNpmSpecifier } from '@doki-land/live2d-loader';
 import * as _doki_land_live2d_renderer from '@doki-land/live2d-renderer';
 import { ModelBackend, compileSharedModelCompile, TextureData, Renderer, ParameterBinding, DrawableMesh, RendererKind } from '@doki-land/live2d-renderer';
@@ -219,7 +219,9 @@ declare class ModelAssetRegistry implements Live2dStageAssets {
     #private;
     constructor(options: ModelAssetRegistryOptions);
     load(source: ModelSource, resolver?: AssetResolver): Promise<ModelAsset>;
-    acquire(source: ModelSource, resolver: AssetResolver | undefined, onProgress?: (payload: LoadProgress) => void): Promise<ModelAssetLease>;
+    acquire(source: ModelSource, resolver: AssetResolver | undefined, onProgress?: (payload: LoadProgress) => void, options?: {
+        signal?: AbortSignal;
+    }): Promise<ModelAssetLease>;
     acquireExisting(asset: ModelAsset): ModelAssetLease;
     destroy(): void;
 }
@@ -250,7 +252,9 @@ declare class ActorModelSlot {
     /** Load-time stable id → binding map (binding.value updated on setParameter). */
     parameterMap(): ReadonlyMap<string, ParameterBinding>;
     resolveParameter(id: string): number | undefined;
-    load(source: ModelSource, resolver?: AssetResolver): Promise<InternalModel>;
+    load(source: ModelSource, resolver?: AssetResolver, options?: {
+        signal?: AbortSignal;
+    }): Promise<InternalModel>;
     loadAsset(asset: ModelAsset): Promise<InternalModel>;
     setParameter(id: string, value: number): void;
     listParameters(): readonly ParameterBinding[];
@@ -285,6 +289,19 @@ declare class Live2dActorImpl implements Live2dActor {
     readonly id: string;
     readonly creationIndex: number;
     constructor(options: CreateActorOptions | undefined, shared: Live2dActorImplOptions);
+    /** Bridge MotionPlayer lifecycle into Stage/facade event buses. */
+    setMotionEventHandlers(handlers: {
+        onStart?: (payload: {
+            group: string;
+            index: number;
+            slot: string;
+        }) => void;
+        onFinish?: (payload: {
+            group: string;
+            index: number;
+            slot: string;
+        }) => void;
+    }): void;
     get model(): InternalModel | null;
     get visible(): boolean;
     set visible(value: boolean);
@@ -296,7 +313,9 @@ declare class Live2dActorImpl implements Live2dActor {
     set order(value: number);
     getTransform(): ActorTransform;
     setTransform(patch: Partial<ActorTransform>): void;
-    load(source: Parameters<Live2dActor["load"]>[0], resolver?: Parameters<Live2dActor["load"]>[1]): Promise<InternalModel>;
+    load(source: Parameters<Live2dActor["load"]>[0], resolver?: Parameters<Live2dActor["load"]>[1], options?: {
+        signal?: AbortSignal;
+    }): Promise<InternalModel>;
     loadAsset(asset: ModelAsset): Promise<InternalModel>;
     setParameter(id: string, value: number): void;
     listParameters(): readonly _doki_land_live2d_renderer.ParameterBinding[];
@@ -362,13 +381,13 @@ declare class Live2dStageImpl implements Live2dStage {
 }
 declare function createLive2dStage(options?: CreateLive2dStageFullOptions): Live2dStage;
 
-interface CreateLive2DOptions {
+interface CreateLive2dOptions {
     backends?: ModelBackend[];
     renderer?: Renderer;
     prefer?: RendererKind[];
     updateMode?: "auto" | "manual";
 }
-interface Live2DRuntime extends Live2DSession {
+interface Live2dRuntime extends Live2dSession {
     readonly renderer: Renderer;
     readonly backends: readonly ModelBackend[];
     readonly stage: Live2dStageImpl;
@@ -399,9 +418,52 @@ interface Live2DRuntime extends Live2DSession {
         quality?: number;
     }): Promise<Blob>;
 }
+/** @deprecated Use `CreateLive2dOptions`. */
+type CreateLive2DOptions = CreateLive2dOptions;
+/** @deprecated Use `Live2dRuntime`. */
+type Live2DRuntime = Live2dRuntime;
 
 /** Wire moc backends and a renderer into one single-actor session. */
-declare function createLive2D(options?: CreateLive2DOptions): Live2DRuntime;
+declare function createLive2d(options?: CreateLive2dOptions): Live2dRuntime;
+/** @deprecated Use `createLive2d`. */
+declare const createLive2D: typeof createLive2d;
+
+/** One physics output destination (parameter id only for the thin gate). */
+interface Physics3Output {
+    readonly destinationId: string;
+}
+/** One PhysicsSettings entry with output destinations. */
+interface Physics3Setting {
+    readonly id: string;
+    readonly outputs: readonly Physics3Output[];
+}
+/**
+ * Parsed Cubism `physics3.json` (minimal).
+ * Full spring / pendulum simulation is intentionally out of scope for this gate.
+ */
+interface Physics3Clip {
+    readonly settings: readonly Physics3Setting[];
+    /** Flattened destination parameter ids from all outputs. */
+    readonly outputParameterIds: readonly string[];
+}
+
+interface Physics3ApplyBinding {
+    readonly value: number;
+}
+/**
+ * Minimal Physics3 apply gate — **not** a full Cubism spring / pendulum solver.
+ *
+ * For each output destination parameter id that exists in `bindings`, performs a
+ * trivial identity step (write current value back). Exists so load → update can
+ * exercise the physics clip API; real physics evaluation is a later milestone.
+ */
+declare function applyPhysics3(clip: Physics3Clip, _deltaTimeSeconds: number, bindings: ReadonlyMap<string, Physics3ApplyBinding>, setParameter: (id: string, value: number) => void): void;
+
+/**
+ * Parse Cubism `physics3.json` enough to expose PhysicsSettings output parameter ids.
+ * Tolerates minimal fixtures (missing / empty PhysicsSettings → empty clip).
+ */
+declare function parsePhysics3(json: unknown): Physics3Clip;
 
 /** Parsed Cubism `pose3.json` / legacy `pose.json` groups. */
 interface Pose3Clip {
@@ -447,16 +509,16 @@ declare function resolveHitAreaName(input: ResolveHitAreaInput): string;
  * `@doki-land/live2d` — public facade.
  *
  * Layout:
- * - `facade/`    — `createLive2D()` default stage + actor entry
+ * - `facade/`    — `createLive2d()` default stage + actor entry
  * - `motion/`    — motion3 parse + playback
  * - `stage/`     — multi-actor stage, assets, transforms
  * - `reexports/` — optional subpath `@doki-land/live2d/{core,loader,renderer}`
  *
  * ```ts
- * import { createLive2D } from "@doki-land/live2d";
+ * import { createLive2d } from "@doki-land/live2d";
  * ```
  */
 
 declare const LIVE2D_VERSION: "0.0.0";
 
-export { type CreateLive2DOptions, type CreateLive2dStageFullOptions, type Expression3Clip, type Expression3Parameter, type ExpressionBlendMode, LIVE2D_VERSION, type Live2DRuntime, type Motion3Clip, type MotionApplySample, MotionPlayer, MotionPriority, type PlayMotionOptions, type Pose3Clip, allocateActorId, applyExpression3Clip, applyPose3Activation, blendMotionLayers, createLive2D, createLive2dStage, evaluateCurve, evaluateMotion3, focusParameterUpdates, parseExpression3, parseMotion3, parsePose3, resolveHitAreaName };
+export { type CreateLive2DOptions, type CreateLive2dOptions, type CreateLive2dStageFullOptions, type Expression3Clip, type Expression3Parameter, type ExpressionBlendMode, LIVE2D_VERSION, type Live2DRuntime, type Live2dRuntime, type Motion3Clip, type MotionApplySample, MotionPlayer, MotionPriority, type Physics3ApplyBinding, type Physics3Clip, type Physics3Output, type Physics3Setting, type PlayMotionOptions, type Pose3Clip, allocateActorId, applyExpression3Clip, applyPhysics3, applyPose3Activation, blendMotionLayers, createLive2D, createLive2d, createLive2dStage, evaluateCurve, evaluateMotion3, focusParameterUpdates, parseExpression3, parseMotion3, parsePhysics3, parsePose3, resolveHitAreaName };

package/dist/index.js

@@ -573,6 +573,60 @@ function optionalNum(v) {
   return typeof v === "number" && Number.isFinite(v) ? v : void 0;
 }
 
+// src/physics/apply-physics3.ts
+function applyPhysics3(clip, _deltaTimeSeconds, bindings, setParameter) {
+  for (const id of clip.outputParameterIds) {
+    const binding = bindings.get(id);
+    if (!binding) continue;
+    setParameter(id, binding.value);
+  }
+}
+
+// src/physics/parse-physics3.ts
+function parsePhysics3(json) {
+  if (!json || typeof json !== "object") {
+    throw new Error(
+      "@doki-land/live2d: physics3 json root must be an object"
+    );
+  }
+  const root = json;
+  const settingsRaw = root.PhysicsSettings;
+  if (settingsRaw === void 0 || settingsRaw === null) {
+    return { settings: [], outputParameterIds: [] };
+  }
+  if (!Array.isArray(settingsRaw)) {
+    throw new Error("@doki-land/live2d: PhysicsSettings must be an array");
+  }
+  const settings = [];
+  const outputParameterIds = [];
+  for (let si = 0; si < settingsRaw.length; si++) {
+    const entry = settingsRaw[si];
+    if (!entry || typeof entry !== "object") {
+      throw new Error(
+        `@doki-land/live2d: PhysicsSettings[${si}] must be an object`
+      );
+    }
+    const rec = entry;
+    const id = typeof rec.Id === "string" ? rec.Id : `PhysicsSetting${si}`;
+    const outputsRaw = rec.Output;
+    const outputs = [];
+    if (Array.isArray(outputsRaw)) {
+      for (let oi = 0; oi < outputsRaw.length; oi++) {
+        const out = outputsRaw[oi];
+        if (!out || typeof out !== "object") continue;
+        const dest = out.Destination;
+        if (!dest || typeof dest !== "object") continue;
+        const destId = dest.Id;
+        if (typeof destId !== "string" || !destId) continue;
+        outputs.push({ destinationId: destId });
+        outputParameterIds.push(destId);
+      }
+    }
+    settings.push({ id, outputs });
+  }
+  return { settings, outputParameterIds };
+}
+
 // src/pose/apply-pose3.ts
 function applyPose3Activation(clip, activatedPartId, setPartOpacity) {
   for (const group of clip.groups) {
@@ -645,6 +699,7 @@ var ActorModelSlot = class {
   #expressionCache = /* @__PURE__ */ new Map();
   #activeExpression = null;
   #poseClip = null;
+  #physicsClip = null;
   constructor(options) {
     this.#assets = options.assets;
     this.#renderer = options.renderer;
@@ -745,6 +800,27 @@ var ActorModelSlot = class {
       this.#poseClip = null;
     }
   }
+  async #loadPhysicsClip() {
+    this.#physicsClip = null;
+    const physicsPath = this.#model?.settings.physics;
+    if (!physicsPath || !this.#lease) return;
+    try {
+      const json = await this.#lease.resolver.fetchJson(physicsPath);
+      this.#physicsClip = parsePhysics3(json);
+    } catch {
+      this.#physicsClip = null;
+    }
+  }
+  #applyPhysicsLayer(deltaTimeSeconds) {
+    if (!this.#physicsClip || !this.#model || !this.#backend) return;
+    applyPhysics3(
+      this.#physicsClip,
+      deltaTimeSeconds,
+      this.#paramById,
+      (id, value) => this.#backend?.setParameter?.(this.#model, id, value)
+    );
+    this.#syncParamCacheFromBackend();
+  }
   #rebuildParamCache() {
     this.#paramById.clear();
     this.#paramIndexById.clear();
@@ -774,24 +850,37 @@ var ActorModelSlot = class {
     }
     return this.#paramIndexById.get(id);
   }
-  async load(source, resolver) {
+  async load(source, resolver, options) {
     const gen = ++this.#loadGeneration;
+    const signal = options?.signal;
+    if (signal?.aborted) {
+      throw new Error("@doki-land/live2d: load cancelled");
+    }
+    const onAbort = () => {
+      this.#loadGeneration += 1;
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
     this.#report({
       stage: "mounting",
       progress: 0.01,
       detail: "prepare draw pass"
     });
     const drawPass = this.ensureDrawPass();
-    const lease = await this.#assets.acquire(
-      source,
-      resolver,
-      (p) => this.#report(p)
-    );
-    if (gen !== this.#loadGeneration) {
-      lease.release();
-      throw new Error("@doki-land/live2d: load cancelled");
+    try {
+      const lease = await this.#assets.acquire(
+        source,
+        resolver,
+        (p) => this.#report(p),
+        { signal }
+      );
+      if (gen !== this.#loadGeneration) {
+        lease.release();
+        throw new Error("@doki-land/live2d: load cancelled");
+      }
+      return await this.#attachLease(lease, drawPass, gen);
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
     }
-    return await this.#attachLease(lease, drawPass, gen);
   }
   async loadAsset(asset) {
     const gen = ++this.#loadGeneration;
@@ -817,6 +906,7 @@ var ActorModelSlot = class {
     this.#motionPlayer.clear();
     this.#activeExpression = null;
     this.#poseClip = null;
+    this.#physicsClip = null;
     this.#releaseLease();
     const { model, backend } = await lease.createInstance(this.#renderer);
     if (gen !== this.#loadGeneration) {
@@ -833,6 +923,7 @@ var ActorModelSlot = class {
     this.#backend = backend;
     this.#rebuildParamCache();
     await this.#loadPoseClip();
+    await this.#loadPhysicsClip();
     this.#report({
       stage: "ready",
       progress: 1,
@@ -907,6 +998,7 @@ var ActorModelSlot = class {
     this.#applyMotionSamples(this.#motionPlayer.update(deltaTimeSeconds));
     this.#tickExpression(deltaTimeSeconds);
     this.#applyExpressionLayer();
+    this.#applyPhysicsLayer(deltaTimeSeconds);
     this.#backend.updateModel(this.#model, deltaTimeSeconds);
     return this.#backend.getDrawables(this.#model);
   }
@@ -946,6 +1038,7 @@ var ActorModelSlot = class {
     this.#motionPlayer.clear();
     this.#activeExpression = null;
     this.#poseClip = null;
+    this.#physicsClip = null;
     if (this.#model && this.#backend) {
       this.#backend.destroyModel(this.#model);
     }
@@ -1171,9 +1264,18 @@ var Live2dActorImpl = class {
     this.#order = options?.order ?? 0;
     this.#slot = new ActorModelSlot({
       assets: shared.assets,
-      renderer: shared.renderer
+      renderer: shared.renderer,
+      onMotionStart: (payload) => this.#onMotionStart?.(payload),
+      onMotionFinish: (payload) => this.#onMotionFinish?.(payload)
     });
   }
+  #onMotionStart = null;
+  #onMotionFinish = null;
+  /** Bridge MotionPlayer lifecycle into Stage/facade event buses. */
+  setMotionEventHandlers(handlers) {
+    this.#onMotionStart = handlers.onStart ?? null;
+    this.#onMotionFinish = handlers.onFinish ?? null;
+  }
   get model() {
     return this.#slot.model;
   }
@@ -1210,11 +1312,11 @@ var Live2dActorImpl = class {
       ...patch
     });
   }
-  async load(source, resolver) {
+  async load(source, resolver, options) {
     if (this.#destroyed) {
       throw new Error("@doki-land/live2d: actor destroyed");
     }
-    return await this.#slot.load(source, resolver);
+    return await this.#slot.load(source, resolver, options);
   }
   async loadAsset(asset) {
     if (this.#destroyed) {
@@ -1363,10 +1465,10 @@ function createSingleActorFacade(stage, actor, backends) {
         }
       );
     },
-    async loadModel(source, resolver) {
+    async loadModel(source, resolver, options) {
       setPhase("loading");
       try {
-        const model = await actor.load(source, resolver);
+        const model = await actor.load(source, resolver, options);
         lastError = null;
         setPhase("live");
         events.emit("ready", { modelId: model.id });
@@ -1479,6 +1581,10 @@ function createSingleActorFacade(stage, actor, backends) {
       events.clear();
     }
   };
+  actor.setMotionEventHandlers({
+    onStart: (payload) => events.emit("motion:start", payload),
+    onFinish: (payload) => events.emit("motion:finish", payload)
+  });
   return runtime;
 }
 
@@ -1608,8 +1714,13 @@ var ModelAssetRegistry = class {
     const entry = await this.#ensureEntry(source, resolver);
     return new ModelAssetHandle(entry);
   }
-  async acquire(source, resolver, onProgress) {
-    const entry = await this.#ensureEntry(source, resolver, onProgress);
+  async acquire(source, resolver, onProgress, options) {
+    const entry = await this.#ensureEntry(
+      source,
+      resolver,
+      onProgress,
+      options
+    );
     entry.refCount += 1;
     return this.#leaseFromEntry(entry);
   }
@@ -1660,13 +1771,19 @@ var ModelAssetRegistry = class {
       }
     };
   }
-  async #ensureEntry(source, resolver, onProgress) {
+  async #ensureEntry(source, resolver, onProgress, options) {
     const key = resolveModelAssetKey(source);
     const existing = this.#entries.get(key);
     if (existing) return existing;
     let pending = this.#inFlight.get(key);
     if (!pending) {
-      pending = this.#compileEntry(key, source, resolver, onProgress);
+      pending = this.#compileEntry(
+        key,
+        source,
+        resolver,
+        onProgress,
+        options
+      );
       this.#inFlight.set(key, pending);
     }
     try {
@@ -1677,8 +1794,12 @@ var ModelAssetRegistry = class {
       this.#inFlight.delete(key);
     }
   }
-  async #compileEntry(key, source, resolver, onProgress) {
+  async #compileEntry(key, source, resolver, onProgress, options) {
     const notify = (payload) => onProgress?.(payload);
+    const signal = options?.signal;
+    if (signal?.aborted) {
+      throw new Error("@doki-land/live2d: load cancelled");
+    }
     notify({
       stage: "resolve",
       progress: 0.02,
@@ -1707,19 +1828,26 @@ var ModelAssetRegistry = class {
         progress: 0.05,
         detail: fetchUrl
       });
-      json = await fetchModelJson(fetchUrl, (u) => {
-        const ratio = u.bytesTotal && u.bytesTotal > 0 ? u.bytesLoaded / u.bytesTotal : 0;
-        notify({
-          stage: "settings",
-          progress: lerp(0.05, 0.22, ratio),
-          detail: fetchUrl,
-          bytesLoaded: u.bytesLoaded,
-          bytesTotal: u.bytesTotal
-        });
-      });
+      json = await fetchModelJson(
+        fetchUrl,
+        (u) => {
+          const ratio = u.bytesTotal && u.bytesTotal > 0 ? u.bytesLoaded / u.bytesTotal : 0;
+          notify({
+            stage: "settings",
+            progress: lerp(0.05, 0.22, ratio),
+            detail: fetchUrl,
+            bytesLoaded: u.bytesLoaded,
+            bytesTotal: u.bytesTotal
+          });
+        },
+        { signal }
+      );
       baseUrl = fetchUrl;
       settingsUrl = fetchUrl;
     }
+    if (signal?.aborted) {
+      throw new Error("@doki-land/live2d: load cancelled");
+    }
     const settings = normalizeModelSettings(json, settingsUrl);
     notify({
       stage: "moc",
@@ -1727,6 +1855,7 @@ var ModelAssetRegistry = class {
       detail: settings.moc
     });
     const assetResolver = resolver ?? createUrlAssetResolver(baseUrl, {
+      signal,
       onBytesProgress: (assetKey, u) => {
         const isMoc = assetKey === settings.moc;
         const ratio = u.bytesTotal && u.bytesTotal > 0 ? u.bytesLoaded / u.bytesTotal : 0;
@@ -1756,6 +1885,9 @@ var ModelAssetRegistry = class {
       detail: `decode ${settings.format}`
     });
     const mocBytes = await assetResolver.fetchBytes(settings.moc);
+    if (signal?.aborted) {
+      throw new Error("@doki-land/live2d: load cancelled");
+    }
     const sharedCompile = compileSharedModelCompile(settings, mocBytes);
     const textures = [];
     if (settings.textures.length > 0) {
@@ -1779,6 +1911,9 @@ var ModelAssetRegistry = class {
         })
       );
     }
+    if (signal?.aborted) {
+      throw new Error("@doki-land/live2d: load cancelled");
+    }
     notify({
       stage: "ready",
       progress: 1,
@@ -2148,7 +2283,7 @@ function createLive2dStage(options) {
 }
 
 // src/facade/create-live2d.ts
-function createLive2D(options = {}) {
+function createLive2d(options = {}) {
   const backends = options.backends ?? [
     createMoc2Backend2(),
     createMoc3Backend2()
@@ -2163,6 +2298,7 @@ function createLive2D(options = {}) {
   });
   return createSingleActorFacade(stage, actor, backends);
 }
+var createLive2D = createLive2d;
 
 // src/index.ts
 var LIVE2D_VERSION = "0.0.0";
@@ -2175,10 +2311,12 @@ export {
   MotionPriority,
   allocateActorId,
   applyExpression3Clip,
+  applyPhysics3,
   applyPose3Activation,
   blendMotionLayers,
   createCanvas2DRenderer,
   createLive2D,
+  createLive2d,
   createLive2dStage,
   createMoc2Backend3 as createMoc2Backend,
   createMoc3Backend3 as createMoc3Backend,
@@ -2195,6 +2333,7 @@ export {
   parseCpuProgram,
   parseExpression3,
   parseMotion3,
+  parsePhysics3,
   parsePose3,
   resolveHitAreaName,
   resolveModelSourceUrl2 as resolveModelSourceUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doki-land/live2d",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "description": "Live2D in the browser — load moc2/moc3 models, Stage + multi-actor, motion; WebGPU/WebGL2/Canvas2D. Main entry for live2d.ts.",
   "type": "module",
   "license": "MIT",
@@ -59,9 +59,9 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@doki-land/live2d-core": "0.0.23",
-    "@doki-land/live2d-loader": "0.0.23",
-    "@doki-land/live2d-renderer": "0.0.23"
+    "@doki-land/live2d-core": "0.0.24",
+    "@doki-land/live2d-loader": "0.0.24",
+    "@doki-land/live2d-renderer": "0.0.24"
   },
   "sideEffects": false
 }

package/src/facade/create-live2d.ts

@@ -5,14 +5,18 @@ import {
 } from "@doki-land/live2d-renderer";
 import { allocateActorId } from "../stage/actor.js";
 import {
-    type CreateLive2DOptions,
+    type CreateLive2dOptions,
     createSingleActorFacade,
-    type Live2DRuntime,
+    type Live2dRuntime,
 } from "../stage/single-facade.js";
 import { createLive2dStage } from "../stage/stage.js";
 
 export type {
+    CreateLive2dOptions,
+    Live2dRuntime,
+    /** @deprecated Use `CreateLive2dOptions`. */
     CreateLive2DOptions,
+    /** @deprecated Use `Live2dRuntime`. */
     Live2DRuntime,
 } from "../stage/single-facade.js";
 export {
@@ -21,7 +25,7 @@ export {
 } from "../stage/single-facade.js";
 
 /** Wire moc backends and a renderer into one single-actor session. */
-export function createLive2D(options: CreateLive2DOptions = {}): Live2DRuntime {
+export function createLive2d(options: CreateLive2dOptions = {}): Live2dRuntime {
     const backends = options.backends ?? [
         createMoc2Backend(),
         createMoc3Backend(),
@@ -37,3 +41,6 @@ export function createLive2D(options: CreateLive2DOptions = {}): Live2DRuntime {
     }) as import("../stage/actor.js").Live2dActorImpl;
     return createSingleActorFacade(stage, actor, backends);
 }
+
+/** @deprecated Use `createLive2d`. */
+export const createLive2D = createLive2d;

package/src/index.ts

@@ -2,13 +2,13 @@
  * `@doki-land/live2d` — public facade.
  *
  * Layout:
- * - `facade/`    — `createLive2D()` default stage + actor entry
+ * - `facade/`    — `createLive2d()` default stage + actor entry
  * - `motion/`    — motion3 parse + playback
  * - `stage/`     — multi-actor stage, assets, transforms
  * - `reexports/` — optional subpath `@doki-land/live2d/{core,loader,renderer}`
  *
  * ```ts
- * import { createLive2D } from "@doki-land/live2d";
+ * import { createLive2d } from "@doki-land/live2d";
  * ```
  */
 
@@ -22,8 +22,8 @@ export type {
     FrameProfile,
     FrameSnapshot,
     InternalModel,
-    Live2DSession,
     Live2dActor,
+    Live2dSession,
     Live2dStage,
     Live2dStageAssets,
     LoadProgress,
@@ -74,8 +74,14 @@ export {
     parseExpression3,
 } from "./expression/index.js";
 export {
-    type CreateLive2DOptions,
+    type CreateLive2dOptions,
+    createLive2d,
+    type Live2dRuntime,
+    /** @deprecated Use `createLive2d`. */
     createLive2D,
+    /** @deprecated Use `CreateLive2dOptions`. */
+    type CreateLive2DOptions,
+    /** @deprecated Use `Live2dRuntime`. */
     type Live2DRuntime,
     MotionPriority,
     type PlayMotionOptions,
@@ -89,6 +95,14 @@ export {
     MotionPlayer,
     parseMotion3,
 } from "./motion/index.js";
+export {
+    applyPhysics3,
+    type Physics3ApplyBinding,
+    type Physics3Clip,
+    type Physics3Output,
+    type Physics3Setting,
+    parsePhysics3,
+} from "./physics/index.js";
 export {
     applyPose3Activation,
     type Pose3Clip,

package/src/physics/apply-physics3.ts

@@ -0,0 +1,26 @@
+import type { Physics3Clip } from "./types.js";
+
+export interface Physics3ApplyBinding {
+    readonly value: number;
+}
+
+/**
+ * Minimal Physics3 apply gate — **not** a full Cubism spring / pendulum solver.
+ *
+ * For each output destination parameter id that exists in `bindings`, performs a
+ * trivial identity step (write current value back). Exists so load → update can
+ * exercise the physics clip API; real physics evaluation is a later milestone.
+ */
+export function applyPhysics3(
+    clip: Physics3Clip,
+    _deltaTimeSeconds: number,
+    bindings: ReadonlyMap<string, Physics3ApplyBinding>,
+    setParameter: (id: string, value: number) => void,
+): void {
+    for (const id of clip.outputParameterIds) {
+        const binding = bindings.get(id);
+        if (!binding) continue;
+        // Identity / zero-step: prove the output walk without changing values.
+        setParameter(id, binding.value);
+    }
+}

package/src/physics/index.ts

@@ -0,0 +1,7 @@
+export { applyPhysics3, type Physics3ApplyBinding } from "./apply-physics3.js";
+export { parsePhysics3 } from "./parse-physics3.js";
+export type {
+    Physics3Clip,
+    Physics3Output,
+    Physics3Setting,
+} from "./types.js";

package/src/physics/parse-physics3.ts

@@ -0,0 +1,52 @@
+import type { Physics3Clip, Physics3Output, Physics3Setting } from "./types.js";
+
+/**
+ * Parse Cubism `physics3.json` enough to expose PhysicsSettings output parameter ids.
+ * Tolerates minimal fixtures (missing / empty PhysicsSettings → empty clip).
+ */
+export function parsePhysics3(json: unknown): Physics3Clip {
+    if (!json || typeof json !== "object") {
+        throw new Error(
+            "@doki-land/live2d: physics3 json root must be an object",
+        );
+    }
+    const root = json as Record<string, unknown>;
+    const settingsRaw = root.PhysicsSettings;
+    if (settingsRaw === undefined || settingsRaw === null) {
+        return { settings: [], outputParameterIds: [] };
+    }
+    if (!Array.isArray(settingsRaw)) {
+        throw new Error("@doki-land/live2d: PhysicsSettings must be an array");
+    }
+
+    const settings: Physics3Setting[] = [];
+    const outputParameterIds: string[] = [];
+
+    for (let si = 0; si < settingsRaw.length; si++) {
+        const entry = settingsRaw[si];
+        if (!entry || typeof entry !== "object") {
+            throw new Error(
+                `@doki-land/live2d: PhysicsSettings[${si}] must be an object`,
+            );
+        }
+        const rec = entry as Record<string, unknown>;
+        const id = typeof rec.Id === "string" ? rec.Id : `PhysicsSetting${si}`;
+        const outputsRaw = rec.Output;
+        const outputs: Physics3Output[] = [];
+        if (Array.isArray(outputsRaw)) {
+            for (let oi = 0; oi < outputsRaw.length; oi++) {
+                const out = outputsRaw[oi];
+                if (!out || typeof out !== "object") continue;
+                const dest = (out as Record<string, unknown>).Destination;
+                if (!dest || typeof dest !== "object") continue;
+                const destId = (dest as Record<string, unknown>).Id;
+                if (typeof destId !== "string" || !destId) continue;
+                outputs.push({ destinationId: destId });
+                outputParameterIds.push(destId);
+            }
+        }
+        settings.push({ id, outputs });
+    }
+
+    return { settings, outputParameterIds };
+}

package/src/physics/types.ts

@@ -0,0 +1,20 @@
+/** One physics output destination (parameter id only for the thin gate). */
+export interface Physics3Output {
+    readonly destinationId: string;
+}
+
+/** One PhysicsSettings entry with output destinations. */
+export interface Physics3Setting {
+    readonly id: string;
+    readonly outputs: readonly Physics3Output[];
+}
+
+/**
+ * Parsed Cubism `physics3.json` (minimal).
+ * Full spring / pendulum simulation is intentionally out of scope for this gate.
+ */
+export interface Physics3Clip {
+    readonly settings: readonly Physics3Setting[];
+    /** Flattened destination parameter ids from all outputs. */
+    readonly outputParameterIds: readonly string[];
+}

package/src/stage/actor-model-slot.ts

@@ -22,6 +22,11 @@ import {
     type PlayMotionOptions,
     parseMotion3,
 } from "../motion/index.js";
+import {
+    applyPhysics3,
+    type Physics3Clip,
+    parsePhysics3,
+} from "../physics/index.js";
 import {
     applyPose3Activation,
     type Pose3Clip,
@@ -72,6 +77,7 @@ export class ActorModelSlot {
         weight: number;
     } | null = null;
     #poseClip: Pose3Clip | null = null;
+    #physicsClip: Physics3Clip | null = null;
 
     constructor(options: ActorModelSlotOptions) {
         this.#assets = options.assets;
@@ -187,6 +193,30 @@ export class ActorModelSlot {
         }
     }
 
+    async #loadPhysicsClip(): Promise<void> {
+        this.#physicsClip = null;
+        const physicsPath = this.#model?.settings.physics;
+        if (!physicsPath || !this.#lease) return;
+        try {
+            const json = await this.#lease.resolver.fetchJson(physicsPath);
+            this.#physicsClip = parsePhysics3(json);
+        } catch {
+            this.#physicsClip = null;
+        }
+    }
+
+    #applyPhysicsLayer(deltaTimeSeconds: number): void {
+        if (!this.#physicsClip || !this.#model || !this.#backend) return;
+        applyPhysics3(
+            this.#physicsClip,
+            deltaTimeSeconds,
+            this.#paramById,
+            (id, value) =>
+                this.#backend?.setParameter?.(this.#model!, id, value),
+        );
+        this.#syncParamCacheFromBackend();
+    }
+
     #rebuildParamCache(): void {
         this.#paramById.clear();
         this.#paramIndexById.clear();
@@ -223,8 +253,17 @@ export class ActorModelSlot {
     async load(
         source: ModelSource,
         resolver?: AssetResolver,
+        options?: { signal?: AbortSignal },
     ): Promise<InternalModel> {
         const gen = ++this.#loadGeneration;
+        const signal = options?.signal;
+        if (signal?.aborted) {
+            throw new Error("@doki-land/live2d: load cancelled");
+        }
+        const onAbort = () => {
+            this.#loadGeneration += 1;
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
         this.#report({
             stage: "mounting",
             progress: 0.01,
@@ -232,15 +271,22 @@ export class ActorModelSlot {
         });
         const drawPass = this.ensureDrawPass();
 
-        const lease = await this.#assets.acquire(source, resolver, (p) =>
-            this.#report(p),
-        );
-        if (gen !== this.#loadGeneration) {
-            lease.release();
-            throw new Error("@doki-land/live2d: load cancelled");
-        }
+        try {
+            const lease = await this.#assets.acquire(
+                source,
+                resolver,
+                (p) => this.#report(p),
+                { signal },
+            );
+            if (gen !== this.#loadGeneration) {
+                lease.release();
+                throw new Error("@doki-land/live2d: load cancelled");
+            }
 
-        return await this.#attachLease(lease, drawPass, gen);
+            return await this.#attachLease(lease, drawPass, gen);
+        } finally {
+            signal?.removeEventListener("abort", onAbort);
+        }
     }
 
     async loadAsset(asset: ModelAsset): Promise<InternalModel> {
@@ -275,6 +321,7 @@ export class ActorModelSlot {
         this.#motionPlayer.clear();
         this.#activeExpression = null;
         this.#poseClip = null;
+        this.#physicsClip = null;
         this.#releaseLease();
 
         const { model, backend } = await lease.createInstance(this.#renderer);
@@ -294,6 +341,7 @@ export class ActorModelSlot {
         this.#backend = backend;
         this.#rebuildParamCache();
         await this.#loadPoseClip();
+        await this.#loadPhysicsClip();
         this.#report({
             stage: "ready",
             progress: 1,
@@ -395,6 +443,7 @@ export class ActorModelSlot {
         this.#applyMotionSamples(this.#motionPlayer.update(deltaTimeSeconds));
         this.#tickExpression(deltaTimeSeconds);
         this.#applyExpressionLayer();
+        this.#applyPhysicsLayer(deltaTimeSeconds);
         this.#backend.updateModel(this.#model, deltaTimeSeconds);
         return this.#backend.getDrawables(this.#model);
     }
@@ -446,6 +495,7 @@ export class ActorModelSlot {
         this.#motionPlayer.clear();
         this.#activeExpression = null;
         this.#poseClip = null;
+        this.#physicsClip = null;
         if (this.#model && this.#backend) {
             this.#backend.destroyModel(this.#model);
         }

package/src/stage/actor.ts

@@ -53,9 +53,35 @@ export class Live2dActorImpl implements Live2dActor {
         this.#slot = new ActorModelSlot({
             assets: shared.assets,
             renderer: shared.renderer,
+            onMotionStart: (payload) => this.#onMotionStart?.(payload),
+            onMotionFinish: (payload) => this.#onMotionFinish?.(payload),
         });
     }
 
+    #onMotionStart:
+        | ((payload: { group: string; index: number; slot: string }) => void)
+        | null = null;
+    #onMotionFinish:
+        | ((payload: { group: string; index: number; slot: string }) => void)
+        | null = null;
+
+    /** Bridge MotionPlayer lifecycle into Stage/facade event buses. */
+    setMotionEventHandlers(handlers: {
+        onStart?: (payload: {
+            group: string;
+            index: number;
+            slot: string;
+        }) => void;
+        onFinish?: (payload: {
+            group: string;
+            index: number;
+            slot: string;
+        }) => void;
+    }): void {
+        this.#onMotionStart = handlers.onStart ?? null;
+        this.#onMotionFinish = handlers.onFinish ?? null;
+    }
+
     get model(): InternalModel | null {
         return this.#slot.model;
     }
@@ -106,11 +132,12 @@ export class Live2dActorImpl implements Live2dActor {
     async load(
         source: Parameters<Live2dActor["load"]>[0],
         resolver?: Parameters<Live2dActor["load"]>[1],
+        options?: { signal?: AbortSignal },
     ): Promise<InternalModel> {
         if (this.#destroyed) {
             throw new Error("@doki-land/live2d: actor destroyed");
         }
-        return await this.#slot.load(source, resolver);
+        return await this.#slot.load(source, resolver, options);
     }
 
     async loadAsset(asset: ModelAsset): Promise<InternalModel> {

package/src/stage/index.ts

@@ -1,8 +1,12 @@
 export { allocateActorId, Live2dActorImpl } from "./actor.js";
 export { ActorModelSlot } from "./actor-model-slot.js";
 export {
-    type CreateLive2DOptions,
+    type CreateLive2dOptions,
     createSingleActorFacade,
+    type Live2dRuntime,
+    /** @deprecated Use `CreateLive2dOptions`. */
+    type CreateLive2DOptions,
+    /** @deprecated Use `Live2dRuntime`. */
     type Live2DRuntime,
 } from "./single-facade.js";
 export { createLive2dStage, Live2dStageImpl } from "./stage.js";

package/src/stage/model-asset-registry.ts

@@ -103,8 +103,14 @@ export class ModelAssetRegistry implements Live2dStageAssets {
         source: ModelSource,
         resolver: AssetResolver | undefined,
         onProgress?: (payload: LoadProgress) => void,
+        options?: { signal?: AbortSignal },
     ): Promise<ModelAssetLease> {
-        const entry = await this.#ensureEntry(source, resolver, onProgress);
+        const entry = await this.#ensureEntry(
+            source,
+            resolver,
+            onProgress,
+            options,
+        );
         entry.refCount += 1;
         return this.#leaseFromEntry(entry);
     }
@@ -166,6 +172,7 @@ export class ModelAssetRegistry implements Live2dStageAssets {
         source: ModelSource,
         resolver?: AssetResolver,
         onProgress?: (payload: LoadProgress) => void,
+        options?: { signal?: AbortSignal },
     ): Promise<SharedModelAssetEntry> {
         const key = resolveModelAssetKey(source);
         const existing = this.#entries.get(key);
@@ -173,7 +180,13 @@ export class ModelAssetRegistry implements Live2dStageAssets {
 
         let pending = this.#inFlight.get(key);
         if (!pending) {
-            pending = this.#compileEntry(key, source, resolver, onProgress);
+            pending = this.#compileEntry(
+                key,
+                source,
+                resolver,
+                onProgress,
+                options,
+            );
             this.#inFlight.set(key, pending);
         }
         try {
@@ -190,8 +203,13 @@ export class ModelAssetRegistry implements Live2dStageAssets {
         source: ModelSource,
         resolver: AssetResolver | undefined,
         onProgress?: (payload: LoadProgress) => void,
+        options?: { signal?: AbortSignal },
     ): Promise<SharedModelAssetEntry> {
         const notify = (payload: LoadProgress) => onProgress?.(payload);
+        const signal = options?.signal;
+        if (signal?.aborted) {
+            throw new Error("@doki-land/live2d: load cancelled");
+        }
 
         notify({
             stage: "resolve",
@@ -231,23 +249,31 @@ export class ModelAssetRegistry implements Live2dStageAssets {
                 progress: 0.05,
                 detail: fetchUrl,
             });
-            json = await fetchModelJson(fetchUrl, (u) => {
-                const ratio =
-                    u.bytesTotal && u.bytesTotal > 0
-                        ? u.bytesLoaded / u.bytesTotal
-                        : 0;
-                notify({
-                    stage: "settings",
-                    progress: lerp(0.05, 0.22, ratio),
-                    detail: fetchUrl,
-                    bytesLoaded: u.bytesLoaded,
-                    bytesTotal: u.bytesTotal,
-                });
-            });
+            json = await fetchModelJson(
+                fetchUrl,
+                (u) => {
+                    const ratio =
+                        u.bytesTotal && u.bytesTotal > 0
+                            ? u.bytesLoaded / u.bytesTotal
+                            : 0;
+                    notify({
+                        stage: "settings",
+                        progress: lerp(0.05, 0.22, ratio),
+                        detail: fetchUrl,
+                        bytesLoaded: u.bytesLoaded,
+                        bytesTotal: u.bytesTotal,
+                    });
+                },
+                { signal },
+            );
             baseUrl = fetchUrl;
             settingsUrl = fetchUrl;
         }
 
+        if (signal?.aborted) {
+            throw new Error("@doki-land/live2d: load cancelled");
+        }
+
         const settings = normalizeModelSettings(json, settingsUrl);
         notify({
             stage: "moc",
@@ -258,6 +284,7 @@ export class ModelAssetRegistry implements Live2dStageAssets {
         const assetResolver =
             resolver ??
             createUrlAssetResolver(baseUrl, {
+                signal,
                 onBytesProgress: (assetKey, u) => {
                     const isMoc = assetKey === settings.moc;
                     const ratio =
@@ -292,6 +319,9 @@ export class ModelAssetRegistry implements Live2dStageAssets {
         });
 
         const mocBytes = await assetResolver.fetchBytes(settings.moc);
+        if (signal?.aborted) {
+            throw new Error("@doki-land/live2d: load cancelled");
+        }
         const sharedCompile = compileSharedModelCompile(settings, mocBytes);
 
         const textures: TextureData[] = [];
@@ -317,6 +347,10 @@ export class ModelAssetRegistry implements Live2dStageAssets {
             );
         }
 
+        if (signal?.aborted) {
+            throw new Error("@doki-land/live2d: load cancelled");
+        }
+
         notify({
             stage: "ready",
             progress: 1,

package/src/stage/single-facade.ts

@@ -1,6 +1,6 @@
 import type {
     FrameSnapshot,
-    Live2DSession,
+    Live2dSession,
     LoadProgress,
     ModelSource,
     SessionPhase,
@@ -18,14 +18,14 @@ import { MotionPriority } from "../motion/index.js";
 import type { Live2dActorImpl } from "./actor.js";
 import type { Live2dStageImpl } from "./stage.js";
 
-export interface CreateLive2DOptions {
+export interface CreateLive2dOptions {
     backends?: ModelBackend[];
     renderer?: Renderer;
     prefer?: RendererKind[];
     updateMode?: "auto" | "manual";
 }
 
-export interface Live2DRuntime extends Live2DSession {
+export interface Live2dRuntime extends Live2dSession {
     readonly renderer: Renderer;
     readonly backends: readonly ModelBackend[];
     readonly stage: Live2dStageImpl;
@@ -73,7 +73,7 @@ export function createSingleActorFacade(
     stage: Live2dStageImpl,
     actor: Live2dActorImpl,
     backends: readonly ModelBackend[],
-): Live2DRuntime {
+): Live2dRuntime {
     const events = new EventEmitter();
     let canvas: HTMLCanvasElement | null = null;
     let phase: SessionPhase = "idle";
@@ -92,7 +92,7 @@ export function createSingleActorFacade(
         generation,
     });
 
-    const runtime: Live2DRuntime = {
+    const runtime: Live2dRuntime = {
         events,
         backends,
         renderer: stage.renderer,
@@ -117,10 +117,10 @@ export function createSingleActorFacade(
                 },
             );
         },
-        async loadModel(source: ModelSource, resolver) {
+        async loadModel(source: ModelSource, resolver, options) {
             setPhase("loading");
             try {
-                const model = await actor.load(source, resolver);
+                const model = await actor.load(source, resolver, options);
                 lastError = null;
                 setPhase("live");
                 events.emit("ready", { modelId: model.id });
@@ -234,7 +234,17 @@ export function createSingleActorFacade(
         },
     };
 
+    actor.setMotionEventHandlers({
+        onStart: (payload) => events.emit("motion:start", payload),
+        onFinish: (payload) => events.emit("motion:finish", payload),
+    });
+
     return runtime;
 }
 
 export { MotionPriority, type PlayMotionOptions };
+
+/** @deprecated Use `CreateLive2dOptions`. */
+export type CreateLive2DOptions = CreateLive2dOptions;
+/** @deprecated Use `Live2dRuntime`. */
+export type Live2DRuntime = Live2dRuntime;