@doki-land/live2d 0.0.22 → 0.0.23

package/dist/index.d.ts

@@ -1,11 +1,32 @@
 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 } 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';
 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';
 export { ModelBackend, ParameterBinding, Renderer, RendererKind, createCanvas2DRenderer, createMoc2Backend, createMoc3Backend, createQuadProgram, createRenderer, createWebGl2Renderer, createWebGpuRenderer, decodeMoc3, evaluateFrame, fingerprintSnapshot, parseCpuProgram, serializeCpuProgram } from '@doki-land/live2d-renderer';
 
+type ExpressionBlendMode = "Add" | "Multiply" | "Override";
+interface Expression3Parameter {
+    readonly id: string;
+    readonly value: number;
+    readonly blend: ExpressionBlendMode;
+}
+/** Parsed Cubism `exp3.json`. */
+interface Expression3Clip {
+    readonly version: number;
+    readonly parameters: readonly Expression3Parameter[];
+}
+
+interface ExpressionApplyBinding {
+    readonly value: number;
+}
+/** Apply expression parameters on top of the current parameter state. */
+declare function applyExpression3Clip(clip: Expression3Clip, weight: number, bindings: ReadonlyMap<string, ExpressionApplyBinding>, setParameter: (id: string, value: number) => void): void;
+
+/** Parse Cubism `exp3.json` (FileFormats/exp3.json.md subset). */
+declare function parseExpression3(json: unknown): Expression3Clip;
+
 /** Cubism motion3 segment kinds (spec). */
 type MotionSegmentKind = "linear" | "bezier" | "stepped" | "inverseStepped";
 type MotionCurveTarget = "Parameter" | "PartOpacity" | "Model";
@@ -234,6 +255,8 @@ declare class ActorModelSlot {
     setParameter(id: string, value: number): void;
     listParameters(): readonly ParameterBinding[];
     listMotionGroups(): Record<string, readonly _doki_land_live2d_core.MotionDefinition[]>;
+    listExpressions(): readonly _doki_land_live2d_core.ExpressionDefinition[];
+    setExpression(name: string | null): Promise<boolean>;
     playMotion(group: string, index?: number, options?: PlayMotionOptions): Promise<boolean>;
     stopMotion(opts?: {
         fade?: boolean;
@@ -292,6 +315,8 @@ declare class Live2dActorImpl implements Live2dActor {
         time: number;
         priority: number;
     }[];
+    listExpressions(): readonly _doki_land_live2d_core.ExpressionDefinition[];
+    setExpression(name: string | null): Promise<boolean>;
     lookAt(stageX: number, stageY: number): void;
     /** Internal: evaluate motion/physics and cache drawables for render. */
     update(deltaTimeSeconds: number): DrawableMesh[] | null;
@@ -300,6 +325,7 @@ declare class Live2dActorImpl implements Live2dActor {
     hitTestStage(stageX: number, stageY: number): Omit<ActorHit, "actor"> | null;
     destroy(): void;
 }
+declare function allocateActorId(prefix?: string): string;
 
 interface CreateLive2dStageFullOptions extends CreateLive2dStageOptions {
     backends?: ModelBackend[];
@@ -322,6 +348,7 @@ declare class Live2dStageImpl implements Live2dStage {
     removeActor(actorOrId: Live2dActor | string): void;
     defineLayers(layers: readonly string[]): void;
     update(deltaTimeSeconds: number): void;
+    onFrame(listener: (deltaTimeSeconds: number) => void): () => void;
     render(): void;
     start(): void;
     pause(): void;
@@ -365,6 +392,8 @@ interface Live2DRuntime extends Live2DSession {
         time: number;
         priority: number;
     }>;
+    listExpressions(): ReadonlyArray<_doki_land_live2d_core.ExpressionDefinition>;
+    setExpression(name: string | null): Promise<boolean>;
     capturePng(opts?: {
         mimeType?: "image/png";
         quality?: number;
@@ -374,6 +403,20 @@ interface Live2DRuntime extends Live2DSession {
 /** Wire moc backends and a renderer into one single-actor session. */
 declare function createLive2D(options?: CreateLive2DOptions): Live2DRuntime;
 
+/** Parsed Cubism `pose3.json` / legacy `pose.json` groups. */
+interface Pose3Clip {
+    readonly groups: readonly (readonly string[])[];
+}
+
+/**
+ * When a part in a pose group becomes visible, hide sibling parts in that group.
+ * Mirrors Cubism Pose minimum semantics for part-opacity switching.
+ */
+declare function applyPose3Activation(clip: Pose3Clip, activatedPartId: string, setPartOpacity: (partId: string, opacity: number) => void): void;
+
+/** Parse Cubism pose file (`pose3.json` or legacy `pose.json`). */
+declare function parsePose3(json: unknown): Pose3Clip;
+
 /**
  * Map canvas focus (-1..1, Y-up) onto commonly used model parameter IDs.
  *
@@ -388,6 +431,18 @@ declare function focusParameterUpdates(parameters: readonly ParameterBinding[] |
     value: number;
 }>;
 
+interface ResolveHitAreaInput {
+    readonly hitAreas: readonly HitAreaDefinition[];
+    readonly drawableIndex: number;
+    /** Art-mesh / drawable id from MOC when available. */
+    readonly artMeshId?: string | null;
+}
+/**
+ * Resolve a triangle hit to a named HitArea when settings id matches the drawable.
+ * Falls back to `drawable:N` when no mapping exists.
+ */
+declare function resolveHitAreaName(input: ResolveHitAreaInput): string;
+
 /**
  * `@doki-land/live2d` — public facade.
  *
@@ -404,4 +459,4 @@ declare function focusParameterUpdates(parameters: readonly ParameterBinding[] |
 
 declare const LIVE2D_VERSION: "0.0.0";
 
-export { type CreateLive2DOptions, type CreateLive2dStageFullOptions, LIVE2D_VERSION, type Live2DRuntime, type Motion3Clip, type MotionApplySample, MotionPlayer, MotionPriority, type PlayMotionOptions, blendMotionLayers, createLive2D, createLive2dStage, evaluateCurve, evaluateMotion3, focusParameterUpdates, parseMotion3 };
+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 };

package/dist/index.js

@@ -20,6 +20,67 @@ import {
   serializeCpuProgram
 } from "@doki-land/live2d-renderer";
 
+// src/expression/apply-expression.ts
+function blendValue(current, target, mode, weight) {
+  if (weight <= 0) return current;
+  if (weight >= 1) {
+    if (mode === "Add") return current + target;
+    if (mode === "Multiply") return current * target;
+    return target;
+  }
+  const full = mode === "Add" ? current + target : mode === "Multiply" ? current * target : target;
+  return current + (full - current) * weight;
+}
+function applyExpression3Clip(clip, weight, bindings, setParameter) {
+  if (weight <= 0) return;
+  for (const p of clip.parameters) {
+    const binding = bindings.get(p.id);
+    if (!binding) continue;
+    setParameter(p.id, blendValue(binding.value, p.value, p.blend, weight));
+  }
+}
+
+// src/expression/parse-expression3.ts
+var BLENDS = /* @__PURE__ */ new Set(["Add", "Multiply", "Override"]);
+function parseBlend(raw) {
+  if (typeof raw !== "string") return "Add";
+  if (raw === "Overwrite" || raw === "Override") return "Override";
+  if (BLENDS.has(raw)) {
+    return raw;
+  }
+  return "Add";
+}
+function parseExpression3(json) {
+  if (!json || typeof json !== "object") {
+    throw new Error("@doki-land/live2d: exp3.json root must be an object");
+  }
+  const root = json;
+  const version = Number(root.Version ?? 3);
+  const paramsRaw = root.Parameters;
+  if (!Array.isArray(paramsRaw)) {
+    throw new Error("@doki-land/live2d: exp3.json missing Parameters");
+  }
+  const parameters = paramsRaw.map((item, index) => {
+    if (!item || typeof item !== "object") {
+      throw new Error(`@doki-land/live2d: Parameters[${index}] invalid`);
+    }
+    const p = item;
+    const id = p.Id;
+    const value = p.Value;
+    if (typeof id !== "string" || typeof value !== "number") {
+      throw new Error(
+        `@doki-land/live2d: Parameters[${index}] needs Id/Value`
+      );
+    }
+    return {
+      id,
+      value,
+      blend: parseBlend(p.Blend)
+    };
+  });
+  return { version, parameters };
+}
+
 // src/facade/create-live2d.ts
 import {
   createMoc2Backend as createMoc2Backend2,
@@ -512,6 +573,62 @@ function optionalNum(v) {
   return typeof v === "number" && Number.isFinite(v) ? v : void 0;
 }
 
+// src/pose/apply-pose3.ts
+function applyPose3Activation(clip, activatedPartId, setPartOpacity) {
+  for (const group of clip.groups) {
+    if (!group.includes(activatedPartId)) continue;
+    for (const partId of group) {
+      setPartOpacity(partId, partId === activatedPartId ? 1 : 0);
+    }
+    return;
+  }
+}
+
+// src/pose/parse-pose3.ts
+function parsePose3(json) {
+  if (!json || typeof json !== "object") {
+    throw new Error("@doki-land/live2d: pose json root must be an object");
+  }
+  const root = json;
+  const groupsRaw = root.Groups;
+  if (!Array.isArray(groupsRaw)) {
+    throw new Error("@doki-land/live2d: pose json missing Groups");
+  }
+  const groups = groupsRaw.map((group, gi) => {
+    if (!Array.isArray(group)) {
+      throw new Error(`@doki-land/live2d: Groups[${gi}] must be array`);
+    }
+    return group.map((entry, ei) => {
+      if (!entry || typeof entry !== "object") {
+        throw new Error(
+          `@doki-land/live2d: Groups[${gi}][${ei}] invalid`
+        );
+      }
+      const id = entry.Id;
+      if (typeof id !== "string" || !id) {
+        throw new Error(
+          `@doki-land/live2d: Groups[${gi}][${ei}] missing Id`
+        );
+      }
+      return id;
+    });
+  });
+  return { groups };
+}
+
+// src/stage/hit-area.ts
+function resolveHitAreaName(input) {
+  const { hitAreas, drawableIndex, artMeshId } = input;
+  const candidates = /* @__PURE__ */ new Set();
+  if (artMeshId) candidates.add(artMeshId);
+  candidates.add(`D_${drawableIndex}`);
+  candidates.add(`${drawableIndex}`);
+  for (const area of hitAreas) {
+    if (candidates.has(area.id)) return area.name;
+  }
+  return `drawable:${drawableIndex}`;
+}
+
 // src/stage/actor-model-slot.ts
 var ActorModelSlot = class {
   #assets;
@@ -525,6 +642,9 @@ var ActorModelSlot = class {
   #loadGeneration = 0;
   #paramById = /* @__PURE__ */ new Map();
   #paramIndexById = /* @__PURE__ */ new Map();
+  #expressionCache = /* @__PURE__ */ new Map();
+  #activeExpression = null;
+  #poseClip = null;
   constructor(options) {
     this.#assets = options.assets;
     this.#renderer = options.renderer;
@@ -559,16 +679,8 @@ var ActorModelSlot = class {
       if (s.weight <= 0) continue;
       if (s.target === "PartOpacity") {
         if (!this.#backend.setPartOpacity) continue;
-        if (s.weight >= 1) {
-          this.#backend.setPartOpacity(this.#model, s.id, s.value);
-        } else {
-          const cur2 = 1;
-          this.#backend.setPartOpacity(
-            this.#model,
-            s.id,
-            cur2 + (s.value - cur2) * s.weight
-          );
-        }
+        const value = s.weight >= 1 ? s.value : 1 + (s.value - 1) * s.weight;
+        this.#setPartOpacityWithPose(s.id, value);
         continue;
       }
       if (s.target !== "Parameter" || !this.#backend.setParameter)
@@ -584,6 +696,54 @@ var ActorModelSlot = class {
         cur + (s.value - cur) * s.weight
       );
     }
+    this.#syncParamCacheFromBackend();
+  }
+  #setPartOpacityWithPose(partId, opacity) {
+    if (!this.#model || !this.#backend?.setPartOpacity) return;
+    if (this.#poseClip && opacity > 0) {
+      applyPose3Activation(this.#poseClip, partId, (id, value) => {
+        this.#backend?.setPartOpacity?.(this.#model, id, value);
+      });
+      return;
+    }
+    this.#backend.setPartOpacity(this.#model, partId, opacity);
+  }
+  #syncParamCacheFromBackend() {
+    if (!this.#model || !this.#backend?.listParameters) return;
+    for (const p of this.#backend.listParameters(this.#model)) {
+      const cached = this.#paramById.get(p.id);
+      if (cached) cached.value = p.value;
+    }
+  }
+  #tickExpression(deltaTimeSeconds) {
+    if (!this.#activeExpression) return;
+    const fadeSeconds = 0.25;
+    const step = deltaTimeSeconds / Math.max(1e-3, fadeSeconds);
+    this.#activeExpression.weight = Math.min(
+      1,
+      this.#activeExpression.weight + step
+    );
+  }
+  #applyExpressionLayer() {
+    if (!this.#activeExpression || !this.#model || !this.#backend) return;
+    applyExpression3Clip(
+      this.#activeExpression.clip,
+      this.#activeExpression.weight,
+      this.#paramById,
+      (id, value) => this.#backend?.setParameter?.(this.#model, id, value)
+    );
+    this.#syncParamCacheFromBackend();
+  }
+  async #loadPoseClip() {
+    this.#poseClip = null;
+    const posePath = this.#model?.settings.pose;
+    if (!posePath || !this.#lease) return;
+    try {
+      const json = await this.#lease.resolver.fetchJson(posePath);
+      this.#poseClip = parsePose3(json);
+    } catch {
+      this.#poseClip = null;
+    }
   }
   #rebuildParamCache() {
     this.#paramById.clear();
@@ -655,6 +815,8 @@ var ActorModelSlot = class {
   }
   async #attachLease(lease, drawPass, gen) {
     this.#motionPlayer.clear();
+    this.#activeExpression = null;
+    this.#poseClip = null;
     this.#releaseLease();
     const { model, backend } = await lease.createInstance(this.#renderer);
     if (gen !== this.#loadGeneration) {
@@ -670,6 +832,7 @@ var ActorModelSlot = class {
     this.#model = model;
     this.#backend = backend;
     this.#rebuildParamCache();
+    await this.#loadPoseClip();
     this.#report({
       stage: "ready",
       progress: 1,
@@ -688,6 +851,28 @@ var ActorModelSlot = class {
   listMotionGroups() {
     return this.#model?.settings.motionGroups ?? {};
   }
+  listExpressions() {
+    return this.#model?.settings.expressions ?? [];
+  }
+  async setExpression(name) {
+    if (!this.#model || !this.#lease) return false;
+    if (name === null) {
+      this.#activeExpression = null;
+      return true;
+    }
+    const def = this.#model.settings.expressions.find(
+      (item) => item.name === name
+    );
+    if (!def) return false;
+    let clip = this.#expressionCache.get(def.file);
+    if (!clip) {
+      const json = await this.#lease.resolver.fetchJson(def.file);
+      clip = parseExpression3(json);
+      this.#expressionCache.set(def.file, clip);
+    }
+    this.#activeExpression = { name, clip, weight: 0 };
+    return true;
+  }
   async playMotion(group, index = 0, options = {}) {
     if (!this.#model || !this.#lease) return false;
     const list = this.#model.settings.motionGroups[group];
@@ -720,6 +905,8 @@ var ActorModelSlot = class {
   update(deltaTimeSeconds) {
     if (!this.#model || !this.#backend || !this.#drawPass) return null;
     this.#applyMotionSamples(this.#motionPlayer.update(deltaTimeSeconds));
+    this.#tickExpression(deltaTimeSeconds);
+    this.#applyExpressionLayer();
     this.#backend.updateModel(this.#model, deltaTimeSeconds);
     return this.#backend.getDrawables(this.#model);
   }
@@ -740,10 +927,15 @@ var ActorModelSlot = class {
         const s1 = (bx - ax) * (modelY - ay) - (by - ay) * (modelX - ax);
         const s2 = (cx - bx) * (modelY - by) - (cy - by) * (modelX - bx);
         if (s >= 0 && s1 >= 0 && s2 >= 0 || s <= 0 && s1 <= 0 && s2 <= 0) {
-          const hitArea = this.#model.settings.hitAreas.find(
-            (h) => h.id === `D_${d.index}` || h.id === `${d.index}`
+          const artMeshId = this.#backend.getDrawableArtMeshId?.(
+            this.#model,
+            d.index
           );
-          return hitArea?.name ?? `drawable:${d.index}`;
+          return resolveHitAreaName({
+            hitAreas: this.#model.settings.hitAreas,
+            drawableIndex: d.index,
+            artMeshId
+          });
         }
       }
     }
@@ -752,6 +944,8 @@ var ActorModelSlot = class {
   destroy() {
     this.#loadGeneration += 1;
     this.#motionPlayer.clear();
+    this.#activeExpression = null;
+    this.#poseClip = null;
     if (this.#model && this.#backend) {
       this.#backend.destroyModel(this.#model);
     }
@@ -1056,6 +1250,12 @@ var Live2dActorImpl = class {
   listPlayingMotions() {
     return this.#slot.listPlayingMotions();
   }
+  listExpressions() {
+    return this.#slot.listExpressions();
+  }
+  setExpression(name) {
+    return this.#slot.setExpression(name);
+  }
   lookAt(stageX, stageY) {
     const { dragX, dragY } = stageFocusDrag(
       stageX,
@@ -1212,6 +1412,12 @@ function createSingleActorFacade(stage, actor, backends) {
     listPlayingMotions() {
       return actor.listPlayingMotions();
     },
+    listExpressions() {
+      return actor.listExpressions();
+    },
+    setExpression(name) {
+      return actor.setExpression(name);
+    },
     async capturePng(opts = {}) {
       if (!canvas) {
         throw new Error(
@@ -1620,6 +1826,7 @@ var Live2dStageImpl = class {
   ]);
   #drawScratch = new StageDrawableScratch();
   #sortedActors = [];
+  #frameListeners = /* @__PURE__ */ new Set();
   #canvas = null;
   #initPromise = null;
   #rafId = null;
@@ -1717,11 +1924,20 @@ var Live2dStageImpl = class {
   }
   update(deltaTimeSeconds) {
     if (this.#destroyed) return;
+    for (const listener of this.#frameListeners) {
+      listener(deltaTimeSeconds);
+    }
     for (const actor of this.#actors.values()) {
       actor.update(deltaTimeSeconds);
     }
     this.#applyPointerTracking();
   }
+  onFrame(listener) {
+    this.#frameListeners.add(listener);
+    return () => {
+      this.#frameListeners.delete(listener);
+    };
+  }
   render() {
     if (this.#destroyed || !this.#canvas) return;
     const sorted = this.#sortedActors;
@@ -1809,6 +2025,7 @@ var Live2dStageImpl = class {
     if (this.#destroyed) return;
     this.#destroyed = true;
     this.stop();
+    this.#frameListeners.clear();
     this.#detachPointerListeners();
     for (const actor of this.#actors.values()) {
       actor.destroy();
@@ -1956,6 +2173,9 @@ export {
   LIVE2D_VERSION,
   MotionPlayer,
   MotionPriority,
+  allocateActorId,
+  applyExpression3Clip,
+  applyPose3Activation,
   blendMotionLayers,
   createCanvas2DRenderer,
   createLive2D,
@@ -1973,7 +2193,10 @@ export {
   fingerprintSnapshot,
   focusParameterUpdates,
   parseCpuProgram,
+  parseExpression3,
   parseMotion3,
+  parsePose3,
+  resolveHitAreaName,
   resolveModelSourceUrl2 as resolveModelSourceUrl,
   resolveNpmSpecifier,
   serializeCpuProgram

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doki-land/live2d",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "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.22",
-    "@doki-land/live2d-loader": "0.0.22",
-    "@doki-land/live2d-renderer": "0.0.22"
+    "@doki-land/live2d-core": "0.0.23",
+    "@doki-land/live2d-loader": "0.0.23",
+    "@doki-land/live2d-renderer": "0.0.23"
   },
   "sideEffects": false
 }

package/src/expression/apply-expression.ts

@@ -0,0 +1,41 @@
+import type { Expression3Clip, ExpressionBlendMode } from "./types.js";
+
+export interface ExpressionApplyBinding {
+    readonly value: number;
+}
+
+function blendValue(
+    current: number,
+    target: number,
+    mode: ExpressionBlendMode,
+    weight: number,
+): number {
+    if (weight <= 0) return current;
+    if (weight >= 1) {
+        if (mode === "Add") return current + target;
+        if (mode === "Multiply") return current * target;
+        return target;
+    }
+    const full =
+        mode === "Add"
+            ? current + target
+            : mode === "Multiply"
+              ? current * target
+              : target;
+    return current + (full - current) * weight;
+}
+
+/** Apply expression parameters on top of the current parameter state. */
+export function applyExpression3Clip(
+    clip: Expression3Clip,
+    weight: number,
+    bindings: ReadonlyMap<string, ExpressionApplyBinding>,
+    setParameter: (id: string, value: number) => void,
+): void {
+    if (weight <= 0) return;
+    for (const p of clip.parameters) {
+        const binding = bindings.get(p.id);
+        if (!binding) continue;
+        setParameter(p.id, blendValue(binding.value, p.value, p.blend, weight));
+    }
+}

package/src/expression/index.ts

@@ -0,0 +1,7 @@
+export { applyExpression3Clip } from "./apply-expression.js";
+export { parseExpression3 } from "./parse-expression3.js";
+export type {
+    Expression3Clip,
+    Expression3Parameter,
+    ExpressionBlendMode,
+} from "./types.js";

package/src/expression/parse-expression3.ts

@@ -0,0 +1,45 @@
+import type { Expression3Clip, ExpressionBlendMode } from "./types.js";
+
+const BLENDS = new Set<ExpressionBlendMode>(["Add", "Multiply", "Override"]);
+
+function parseBlend(raw: unknown): ExpressionBlendMode {
+    if (typeof raw !== "string") return "Add";
+    // Cubism official spelling is `Overwrite`; keep `Override` as an alias.
+    if (raw === "Overwrite" || raw === "Override") return "Override";
+    if (BLENDS.has(raw as ExpressionBlendMode)) {
+        return raw as ExpressionBlendMode;
+    }
+    return "Add";
+}
+
+/** Parse Cubism `exp3.json` (FileFormats/exp3.json.md subset). */
+export function parseExpression3(json: unknown): Expression3Clip {
+    if (!json || typeof json !== "object") {
+        throw new Error("@doki-land/live2d: exp3.json root must be an object");
+    }
+    const root = json as Record<string, unknown>;
+    const version = Number(root.Version ?? 3);
+    const paramsRaw = root.Parameters;
+    if (!Array.isArray(paramsRaw)) {
+        throw new Error("@doki-land/live2d: exp3.json missing Parameters");
+    }
+    const parameters = paramsRaw.map((item, index) => {
+        if (!item || typeof item !== "object") {
+            throw new Error(`@doki-land/live2d: Parameters[${index}] invalid`);
+        }
+        const p = item as Record<string, unknown>;
+        const id = p.Id;
+        const value = p.Value;
+        if (typeof id !== "string" || typeof value !== "number") {
+            throw new Error(
+                `@doki-land/live2d: Parameters[${index}] needs Id/Value`,
+            );
+        }
+        return {
+            id,
+            value,
+            blend: parseBlend(p.Blend),
+        };
+    });
+    return { version, parameters };
+}

package/src/expression/types.ts

@@ -0,0 +1,13 @@
+export type ExpressionBlendMode = "Add" | "Multiply" | "Override";
+
+export interface Expression3Parameter {
+    readonly id: string;
+    readonly value: number;
+    readonly blend: ExpressionBlendMode;
+}
+
+/** Parsed Cubism `exp3.json`. */
+export interface Expression3Clip {
+    readonly version: number;
+    readonly parameters: readonly Expression3Parameter[];
+}

package/src/index.ts

@@ -66,6 +66,13 @@ export {
     type RendererKind,
     serializeCpuProgram,
 } from "@doki-land/live2d-renderer";
+export {
+    applyExpression3Clip,
+    type Expression3Clip,
+    type Expression3Parameter,
+    type ExpressionBlendMode,
+    parseExpression3,
+} from "./expression/index.js";
 export {
     type CreateLive2DOptions,
     createLive2D,
@@ -82,7 +89,14 @@ export {
     MotionPlayer,
     parseMotion3,
 } from "./motion/index.js";
+export {
+    applyPose3Activation,
+    type Pose3Clip,
+    parsePose3,
+} from "./pose/index.js";
+export { allocateActorId } from "./stage/actor.js";
 export { focusParameterUpdates } from "./stage/assets/focus.js";
+export { resolveHitAreaName } from "./stage/hit-area.js";
 export {
     type CreateLive2dStageFullOptions,
     createLive2dStage,

package/src/pose/apply-pose3.ts

@@ -0,0 +1,19 @@
+import type { Pose3Clip } from "./types.js";
+
+/**
+ * When a part in a pose group becomes visible, hide sibling parts in that group.
+ * Mirrors Cubism Pose minimum semantics for part-opacity switching.
+ */
+export function applyPose3Activation(
+    clip: Pose3Clip,
+    activatedPartId: string,
+    setPartOpacity: (partId: string, opacity: number) => void,
+): void {
+    for (const group of clip.groups) {
+        if (!group.includes(activatedPartId)) continue;
+        for (const partId of group) {
+            setPartOpacity(partId, partId === activatedPartId ? 1 : 0);
+        }
+        return;
+    }
+}

package/src/pose/index.ts

@@ -0,0 +1,3 @@
+export { applyPose3Activation } from "./apply-pose3.js";
+export { parsePose3 } from "./parse-pose3.js";
+export type { Pose3Clip } from "./types.js";

package/src/pose/parse-pose3.ts

@@ -0,0 +1,33 @@
+import type { Pose3Clip } from "./types.js";
+
+/** Parse Cubism pose file (`pose3.json` or legacy `pose.json`). */
+export function parsePose3(json: unknown): Pose3Clip {
+    if (!json || typeof json !== "object") {
+        throw new Error("@doki-land/live2d: pose json root must be an object");
+    }
+    const root = json as Record<string, unknown>;
+    const groupsRaw = root.Groups;
+    if (!Array.isArray(groupsRaw)) {
+        throw new Error("@doki-land/live2d: pose json missing Groups");
+    }
+    const groups = groupsRaw.map((group, gi) => {
+        if (!Array.isArray(group)) {
+            throw new Error(`@doki-land/live2d: Groups[${gi}] must be array`);
+        }
+        return group.map((entry, ei) => {
+            if (!entry || typeof entry !== "object") {
+                throw new Error(
+                    `@doki-land/live2d: Groups[${gi}][${ei}] invalid`,
+                );
+            }
+            const id = (entry as Record<string, unknown>).Id;
+            if (typeof id !== "string" || !id) {
+                throw new Error(
+                    `@doki-land/live2d: Groups[${gi}][${ei}] missing Id`,
+                );
+            }
+            return id;
+        });
+    });
+    return { groups };
+}

package/src/pose/types.ts

@@ -0,0 +1,4 @@
+/** Parsed Cubism `pose3.json` / legacy `pose.json` groups. */
+export interface Pose3Clip {
+    readonly groups: readonly (readonly string[])[];
+}

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

@@ -11,12 +11,23 @@ import type {
     ParameterBinding,
     Renderer,
 } from "@doki-land/live2d-renderer";
+import {
+    applyExpression3Clip,
+    type Expression3Clip,
+    parseExpression3,
+} from "../expression/index.js";
 import {
     MotionPlayer,
     MotionPriority,
     type PlayMotionOptions,
     parseMotion3,
 } from "../motion/index.js";
+import {
+    applyPose3Activation,
+    type Pose3Clip,
+    parsePose3,
+} from "../pose/index.js";
+import { resolveHitAreaName } from "./hit-area.js";
 import type {
     ModelAssetLease,
     ModelAssetRegistry,
@@ -54,6 +65,13 @@ export class ActorModelSlot {
     #loadGeneration = 0;
     readonly #paramById = new Map<string, ParameterBinding>();
     readonly #paramIndexById = new Map<string, number>();
+    #expressionCache = new Map<string, Expression3Clip>();
+    #activeExpression: {
+        name: string;
+        clip: Expression3Clip;
+        weight: number;
+    } | null = null;
+    #poseClip: Pose3Clip | null = null;
 
     constructor(options: ActorModelSlotOptions) {
         this.#assets = options.assets;
@@ -95,16 +113,9 @@ export class ActorModelSlot {
             if (s.weight <= 0) continue;
             if (s.target === "PartOpacity") {
                 if (!this.#backend.setPartOpacity) continue;
-                if (s.weight >= 1) {
-                    this.#backend.setPartOpacity(this.#model, s.id, s.value);
-                } else {
-                    const cur = 1;
-                    this.#backend.setPartOpacity(
-                        this.#model,
-                        s.id,
-                        cur + (s.value - cur) * s.weight,
-                    );
-                }
+                const value =
+                    s.weight >= 1 ? s.value : 1 + (s.value - 1) * s.weight;
+                this.#setPartOpacityWithPose(s.id, value);
                 continue;
             }
             if (s.target !== "Parameter" || !this.#backend.setParameter)
@@ -120,6 +131,60 @@ export class ActorModelSlot {
                 cur + (s.value - cur) * s.weight,
             );
         }
+        this.#syncParamCacheFromBackend();
+    }
+
+    #setPartOpacityWithPose(partId: string, opacity: number): void {
+        if (!this.#model || !this.#backend?.setPartOpacity) return;
+        if (this.#poseClip && opacity > 0) {
+            applyPose3Activation(this.#poseClip, partId, (id, value) => {
+                this.#backend?.setPartOpacity?.(this.#model!, id, value);
+            });
+            return;
+        }
+        this.#backend.setPartOpacity(this.#model, partId, opacity);
+    }
+
+    #syncParamCacheFromBackend(): void {
+        if (!this.#model || !this.#backend?.listParameters) return;
+        for (const p of this.#backend.listParameters(this.#model)) {
+            const cached = this.#paramById.get(p.id);
+            if (cached) (cached as { value: number }).value = p.value;
+        }
+    }
+
+    #tickExpression(deltaTimeSeconds: number): void {
+        if (!this.#activeExpression) return;
+        const fadeSeconds = 0.25;
+        const step = deltaTimeSeconds / Math.max(0.001, fadeSeconds);
+        this.#activeExpression.weight = Math.min(
+            1,
+            this.#activeExpression.weight + step,
+        );
+    }
+
+    #applyExpressionLayer(): void {
+        if (!this.#activeExpression || !this.#model || !this.#backend) return;
+        applyExpression3Clip(
+            this.#activeExpression.clip,
+            this.#activeExpression.weight,
+            this.#paramById,
+            (id, value) =>
+                this.#backend?.setParameter?.(this.#model!, id, value),
+        );
+        this.#syncParamCacheFromBackend();
+    }
+
+    async #loadPoseClip(): Promise<void> {
+        this.#poseClip = null;
+        const posePath = this.#model?.settings.pose;
+        if (!posePath || !this.#lease) return;
+        try {
+            const json = await this.#lease.resolver.fetchJson(posePath);
+            this.#poseClip = parsePose3(json);
+        } catch {
+            this.#poseClip = null;
+        }
     }
 
     #rebuildParamCache(): void {
@@ -208,6 +273,8 @@ export class ActorModelSlot {
         gen: number,
     ): Promise<InternalModel> {
         this.#motionPlayer.clear();
+        this.#activeExpression = null;
+        this.#poseClip = null;
         this.#releaseLease();
 
         const { model, backend } = await lease.createInstance(this.#renderer);
@@ -226,6 +293,7 @@ export class ActorModelSlot {
         this.#model = model;
         this.#backend = backend;
         this.#rebuildParamCache();
+        await this.#loadPoseClip();
         this.#report({
             stage: "ready",
             progress: 1,
@@ -251,6 +319,30 @@ export class ActorModelSlot {
         return this.#model?.settings.motionGroups ?? {};
     }
 
+    listExpressions(): readonly import("@doki-land/live2d-core").ExpressionDefinition[] {
+        return this.#model?.settings.expressions ?? [];
+    }
+
+    async setExpression(name: string | null): Promise<boolean> {
+        if (!this.#model || !this.#lease) return false;
+        if (name === null) {
+            this.#activeExpression = null;
+            return true;
+        }
+        const def = this.#model.settings.expressions.find(
+            (item) => item.name === name,
+        );
+        if (!def) return false;
+        let clip = this.#expressionCache.get(def.file);
+        if (!clip) {
+            const json = await this.#lease.resolver.fetchJson(def.file);
+            clip = parseExpression3(json);
+            this.#expressionCache.set(def.file, clip);
+        }
+        this.#activeExpression = { name, clip, weight: 0 };
+        return true;
+    }
+
     async playMotion(
         group: string,
         index = 0,
@@ -301,6 +393,8 @@ export class ActorModelSlot {
     update(deltaTimeSeconds: number): DrawableMesh[] | null {
         if (!this.#model || !this.#backend || !this.#drawPass) return null;
         this.#applyMotionSamples(this.#motionPlayer.update(deltaTimeSeconds));
+        this.#tickExpression(deltaTimeSeconds);
+        this.#applyExpressionLayer();
         this.#backend.updateModel(this.#model, deltaTimeSeconds);
         return this.#backend.getDrawables(this.#model);
     }
@@ -332,10 +426,15 @@ export class ActorModelSlot {
                     (s >= 0 && s1 >= 0 && s2 >= 0) ||
                     (s <= 0 && s1 <= 0 && s2 <= 0)
                 ) {
-                    const hitArea = this.#model.settings.hitAreas.find(
-                        (h) => h.id === `D_${d.index}` || h.id === `${d.index}`,
+                    const artMeshId = this.#backend.getDrawableArtMeshId?.(
+                        this.#model,
+                        d.index,
                     );
-                    return hitArea?.name ?? `drawable:${d.index}`;
+                    return resolveHitAreaName({
+                        hitAreas: this.#model.settings.hitAreas,
+                        drawableIndex: d.index,
+                        artMeshId,
+                    });
                 }
             }
         }
@@ -345,6 +444,8 @@ export class ActorModelSlot {
     destroy(): void {
         this.#loadGeneration += 1;
         this.#motionPlayer.clear();
+        this.#activeExpression = null;
+        this.#poseClip = null;
         if (this.#model && this.#backend) {
             this.#backend.destroyModel(this.#model);
         }

package/src/stage/actor.ts

@@ -160,6 +160,14 @@ export class Live2dActorImpl implements Live2dActor {
         return this.#slot.listPlayingMotions();
     }
 
+    listExpressions() {
+        return this.#slot.listExpressions();
+    }
+
+    setExpression(name: string | null) {
+        return this.#slot.setExpression(name);
+    }
+
     lookAt(stageX: number, stageY: number): void {
         const { dragX, dragY } = stageFocusDrag(
             stageX,

package/src/stage/hit-area.ts

@@ -0,0 +1,24 @@
+import type { HitAreaDefinition } from "@doki-land/live2d-core";
+
+export interface ResolveHitAreaInput {
+    readonly hitAreas: readonly HitAreaDefinition[];
+    readonly drawableIndex: number;
+    /** Art-mesh / drawable id from MOC when available. */
+    readonly artMeshId?: string | null;
+}
+
+/**
+ * Resolve a triangle hit to a named HitArea when settings id matches the drawable.
+ * Falls back to `drawable:N` when no mapping exists.
+ */
+export function resolveHitAreaName(input: ResolveHitAreaInput): string {
+    const { hitAreas, drawableIndex, artMeshId } = input;
+    const candidates = new Set<string>();
+    if (artMeshId) candidates.add(artMeshId);
+    candidates.add(`D_${drawableIndex}`);
+    candidates.add(`${drawableIndex}`);
+    for (const area of hitAreas) {
+        if (candidates.has(area.id)) return area.name;
+    }
+    return `drawable:${drawableIndex}`;
+}

package/src/stage/single-facade.ts

@@ -54,6 +54,10 @@ export interface Live2DRuntime extends Live2DSession {
         time: number;
         priority: number;
     }>;
+    listExpressions(): ReadonlyArray<
+        import("@doki-land/live2d-core").ExpressionDefinition
+    >;
+    setExpression(name: string | null): Promise<boolean>;
     capturePng(opts?: {
         mimeType?: "image/png";
         quality?: number;
@@ -162,6 +166,12 @@ export function createSingleActorFacade(
         listPlayingMotions() {
             return actor.listPlayingMotions();
         },
+        listExpressions() {
+            return actor.listExpressions();
+        },
+        setExpression(name) {
+            return actor.setExpression(name);
+        },
         async capturePng(opts = {}) {
             if (!canvas) {
                 throw new Error(

package/src/stage/stage.ts

@@ -67,6 +67,7 @@ export class Live2dStageImpl implements Live2dStage {
     ]);
     readonly #drawScratch = new StageDrawableScratch();
     readonly #sortedActors: Live2dActorImpl[] = [];
+    readonly #frameListeners = new Set<(deltaTimeSeconds: number) => void>();
 
     #canvas: HTMLCanvasElement | null = null;
     #initPromise: Promise<void> | null = null;
@@ -182,12 +183,22 @@ export class Live2dStageImpl implements Live2dStage {
 
     update(deltaTimeSeconds: number): void {
         if (this.#destroyed) return;
+        for (const listener of this.#frameListeners) {
+            listener(deltaTimeSeconds);
+        }
         for (const actor of this.#actors.values()) {
             actor.update(deltaTimeSeconds);
         }
         this.#applyPointerTracking();
     }
 
+    onFrame(listener: (deltaTimeSeconds: number) => void): () => void {
+        this.#frameListeners.add(listener);
+        return () => {
+            this.#frameListeners.delete(listener);
+        };
+    }
+
     render(): void {
         if (this.#destroyed || !this.#canvas) return;
         const sorted = this.#sortedActors;
@@ -291,6 +302,7 @@ export class Live2dStageImpl implements Live2dStage {
         if (this.#destroyed) return;
         this.#destroyed = true;
         this.stop();
+        this.#frameListeners.clear();
         this.#detachPointerListeners();
         for (const actor of this.#actors.values()) {
             actor.destroy();