@doki-land/live2d 0.0.22 → 0.0.24

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';
-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';
 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";
@@ -198,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;
 }
@@ -229,11 +252,15 @@ 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[];
     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;
@@ -262,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);
@@ -273,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[];
@@ -292,6 +334,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 +344,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 +367,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;
@@ -335,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;
@@ -365,14 +411,73 @@ 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;
     }): 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 {
+    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,20 +493,32 @@ 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.
  *
  * 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, LIVE2D_VERSION, type Live2DRuntime, type Motion3Clip, type MotionApplySample, MotionPlayer, MotionPriority, type PlayMotionOptions, blendMotionLayers, createLive2D, createLive2dStage, evaluateCurve, evaluateMotion3, focusParameterUpdates, parseMotion3 };
+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 };