@doki-land/live2d-core 0.0.0 → 0.0.12

package/README.md

@@ -1 +1,3 @@
-# @doki-land/live2d-core placeholder
+# @doki-land/live2d-core
+
+live2d.ts package 0.0.12.

package/dist/index.d.ts

@@ -0,0 +1,346 @@
+/**
+ * Internal loading / session contracts shared across packages.
+ * Format decode and GPU details stay in live2d-renderer.
+ */
+/** How the host names a model settings document. */
+type ModelSource = string | {
+    readonly kind: "url";
+    readonly url: string;
+} | {
+    readonly kind: "json";
+    readonly json: unknown;
+    readonly baseUrl: string;
+} | {
+    readonly kind: "npm";
+    /** Package name, optionally with `@version` (e.g. `live2d-widget-model-hijiki@1.0.5`). */
+    readonly package: string;
+    /** Path inside the package to model JSON. */
+    readonly path: string;
+    /** Optional CDN base; default is applied by the loader. */
+    readonly cdnBase?: string;
+};
+declare function modelSourceUrl(source: ModelSource): string;
+/** Relative asset key as declared in settings (moc, texture, motion, …). */
+type AssetKey = string;
+/** Resolve and fetch assets relative to a model settings URL. */
+interface AssetResolver {
+    readonly baseUrl: string;
+    resolve(key: AssetKey): string;
+    fetchJson(key: AssetKey): Promise<unknown>;
+    fetchBytes(key: AssetKey): Promise<ArrayBuffer>;
+}
+/** Session lifecycle (facade state machine). */
+type SessionPhase = "idle" | "mounting" | "ready" | "loading" | "live" | "error" | "destroyed";
+interface SessionState {
+    readonly phase: SessionPhase;
+    readonly lastError: unknown | null;
+    readonly generation: number;
+}
+
+/** Model binary family (file extension / settings shape). */
+type ModelFormat = "moc2" | "moc3";
+/** Normalized, format-agnostic model settings. */
+interface ModelSettings {
+    format: ModelFormat;
+    url: string;
+    name?: string;
+    moc: string;
+    textures: string[];
+    motionGroups: Record<string, MotionDefinition[]>;
+    expressions: ExpressionDefinition[];
+    physics?: string;
+    pose?: string;
+    hitAreas: HitAreaDefinition[];
+    layout?: Record<string, number>;
+}
+interface MotionDefinition {
+    file: string;
+    sound?: string;
+    fadeInTime?: number;
+    fadeOutTime?: number;
+}
+interface ExpressionDefinition {
+    name: string;
+    file: string;
+}
+interface HitAreaDefinition {
+    name: string;
+    id: string;
+}
+/** Opaque in-memory model handle. */
+interface InternalModel {
+    readonly id: string;
+    readonly settings: ModelSettings;
+    readonly format: ModelFormat;
+}
+
+/**
+ * Settings JSON format detection (moc2 vs moc3).
+ * Shared by loader normalize and renderer backends — keep binary peek in renderer.
+ */
+
+/** Detect moc2 vs moc3 from model settings JSON shape. Returns null if unknown. */
+declare function detectModelSettingsFormat(json: unknown): ModelFormat | null;
+
+/** Load pipeline stage for progress UI. */
+type LoadProgressStage = "mounting" | "resolve" | "settings" | "moc" | "textures" | "decode" | "ready";
+interface LoadProgress {
+    readonly stage: LoadProgressStage;
+    /** Overall 0..1 */
+    readonly progress: number;
+    readonly detail?: string;
+    readonly bytesLoaded?: number;
+    readonly bytesTotal?: number | null;
+}
+/** Per-frame timing / mesh cost for Status / profiler UIs. */
+interface FrameProfile {
+    /** Instantaneous FPS from wall dt (0 if first frame). */
+    readonly fps: number;
+    /** EMA-smoothed FPS for readable UI. */
+    readonly fpsSmooth: number;
+    /** Whole `update()` wall time in ms. */
+    readonly frameMs: number;
+    /** `updateModel` + `getDrawables` in ms. */
+    readonly evaluateMs: number;
+    /** `beginFrame` + `draw` + `endFrame` in ms. */
+    readonly drawMs: number;
+    readonly drawableCount: number;
+    /** Sum of drawable vertex counts (xy pairs). */
+    readonly vertexCount: number;
+    /** Sum of drawable index counts. */
+    readonly indexCount: number;
+}
+/** Minimal event bus used by sessions and loaders. */
+type Live2DEventMap = {
+    ready: {
+        modelId: string;
+    };
+    error: {
+        error: unknown;
+    };
+    progress: LoadProgress;
+    /** Fired after each successful `update()` while live. */
+    profile: FrameProfile;
+    hit: {
+        area: string;
+        x: number;
+        y: number;
+    };
+    "motion:start": {
+        group: string;
+        index: number;
+        slot: string;
+    };
+    "motion:finish": {
+        group: string;
+        index: number;
+        slot: string;
+    };
+    phase: {
+        phase: string;
+        generation: number;
+    };
+};
+type Live2DEventName = keyof Live2DEventMap;
+type Live2DListener<K extends Live2DEventName> = (payload: Live2DEventMap[K]) => void;
+declare class EventEmitter {
+    #private;
+    on<K extends Live2DEventName>(event: K, listener: Live2DListener<K>): () => void;
+    off<K extends Live2DEventName>(event: K, listener: Live2DListener<K>): void;
+    emit<K extends Live2DEventName>(event: K, payload: Live2DEventMap[K]): void;
+    clear(): void;
+}
+
+/**
+ * CPU frame output — format-agnostic mesh list ready for any RenderDevice.
+ */
+/** Blend modes aligned with renderer DrawableMesh. */
+declare const FrameBlendMode: {
+    readonly Normal: 0;
+    readonly Additive: 1;
+    readonly Multiplicative: 2;
+};
+type FrameBlendMode = (typeof FrameBlendMode)[keyof typeof FrameBlendMode];
+/** One drawable after CPU deform for a single frame. */
+interface FrameDrawable {
+    readonly index: number;
+    readonly textureIndex: number;
+    /** Interleaved x,y in model space. */
+    readonly positions: Float32Array;
+    readonly uvs: Float32Array;
+    readonly indices: Uint16Array;
+    readonly opacity: number;
+    readonly blendMode: FrameBlendMode;
+    readonly renderOrder: number;
+    readonly visible: boolean;
+    readonly invertedMask: boolean;
+    readonly maskIndices: readonly number[];
+}
+/** Immutable CPU snapshot consumed by GPU backends or golden tests. */
+interface FrameSnapshot {
+    readonly timeSeconds: number;
+    readonly drawables: readonly FrameDrawable[];
+}
+
+/**
+ * CPU model program / instance shapes (format adapters fill these).
+ */
+interface ParameterProgram {
+    readonly id: string;
+    readonly min: number;
+    readonly max: number;
+    readonly defaultValue: number;
+}
+interface DrawableProgram {
+    readonly index: number;
+    readonly textureIndex: number;
+    /** Rest-pose x,y pairs. */
+    readonly positions: Float32Array;
+    readonly uvs: Float32Array;
+    readonly indices: Uint16Array;
+    readonly opacity: number;
+    readonly renderOrder: number;
+    /** {@link FrameBlendMode} value. */
+    readonly blendMode: number;
+    readonly invertedMask: boolean;
+    /** Indices into `ModelProgram.drawables` used as clipping masks. */
+    readonly maskIndices: readonly number[];
+    readonly visible: boolean;
+    /**
+     * Optional linear deform driven by one parameter.
+     * `deltas[i] = positions_at_max[i] - rest[i]`.
+     */
+    readonly deformParamIndex: number;
+    readonly deformDeltas: Float32Array | null;
+}
+/** Static topology + deform tables after decode. */
+interface ModelProgram {
+    readonly format: "moc2" | "moc3";
+    /** Codec tag, e.g. `cpu-program` or `moc3`. */
+    readonly codec: string;
+    readonly parameters: readonly ParameterProgram[];
+    readonly drawables: readonly DrawableProgram[];
+}
+/** Mutable runtime values over a ModelProgram. */
+interface ModelInstance {
+    readonly program: ModelProgram;
+    /** Parallel to program.parameters. */
+    readonly parameterValues: Float32Array;
+    timeSeconds: number;
+}
+
+/** High-level runtime session for one mounted surface. */
+interface Live2DSession {
+    readonly events: EventEmitter;
+    readonly model: InternalModel | null;
+    readonly state: SessionState;
+    mount(canvas: HTMLCanvasElement): void;
+    loadModel(source: ModelSource, resolver?: AssetResolver): Promise<InternalModel>;
+    /** Latest CPU frame after update, or null if no model. */
+    captureFrame(): FrameSnapshot | null;
+    update(deltaTimeSeconds: number): void;
+    hitTest(x: number, y: number): string | null;
+    destroy(): void;
+}
+declare function createSessionStub(): Live2DSession;
+
+/** Normalized stage placement for one actor (0,0) top-left → (1,1) bottom-right. */
+interface ActorTransform {
+    /** Anchor point X in stage space. */
+    x: number;
+    /** Anchor point Y in stage space. */
+    y: number;
+    /** Uniform scale; ignored when `scaleX` / `scaleY` are set. */
+    scale?: number;
+    scaleX?: number;
+    scaleY?: number;
+    /** Radians, counter-clockwise. */
+    rotation?: number;
+    /** Horizontal anchor within the model bounds (0 = left, 1 = right). */
+    anchorX?: number;
+    /** Vertical anchor within the model bounds (0 = top, 1 = bottom in stage space). */
+    anchorY?: number;
+}
+declare const DEFAULT_ACTOR_TRANSFORM: Readonly<ActorTransform>;
+type PointerTrackingMode = "all" | "focused" | "hovered" | "nearest" | "none" | "custom";
+interface PointerTrackingPolicy {
+    mode: PointerTrackingMode;
+    /** Used when `mode` is `custom`. */
+    targetActorId?: string;
+}
+interface CreateActorOptions {
+    id?: string;
+    transform?: Partial<ActorTransform>;
+    layer?: string;
+    order?: number;
+    visible?: boolean;
+    opacity?: number;
+}
+interface ActorHit {
+    readonly actor: Live2dActor;
+    readonly actorId: string;
+    readonly area: string;
+    readonly drawableIndex: number;
+    readonly stageX: number;
+    readonly stageY: number;
+    readonly localX: number;
+    readonly localY: number;
+}
+interface StagePointerEvent {
+    readonly actor: Live2dActor | null;
+    readonly actorId: string | null;
+    readonly area: string | null;
+    readonly stageX: number;
+    readonly stageY: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly hit: ActorHit | null;
+}
+type StageUpdateMode = "auto" | "manual";
+interface CreateLive2dStageOptions {
+    updateMode?: StageUpdateMode;
+}
+/** Read-only actor surface exposed by the stage. */
+interface Live2dActor {
+    readonly id: string;
+    readonly model: InternalModel | null;
+    readonly visible: boolean;
+    readonly opacity: number;
+    readonly layer: string;
+    readonly order: number;
+    readonly creationIndex: number;
+    getTransform(): ActorTransform;
+    setTransform(patch: Partial<ActorTransform>): void;
+    load(source: ModelSource, resolver?: AssetResolver): Promise<InternalModel>;
+    setParameter(id: string, value: number): void;
+    lookAt(stageX: number, stageY: number): void;
+    destroy(): void;
+}
+/** Multi-character stage owning one canvas surface and shared renderer. */
+interface Live2dStage {
+    readonly actors: readonly Live2dActor[];
+    mount(canvas: HTMLCanvasElement): Promise<void>;
+    createActor(options?: CreateActorOptions): Live2dActor;
+    removeActor(actor: Live2dActor | string): void;
+    defineLayers(layers: readonly string[]): void;
+    update(deltaTimeSeconds: number): void;
+    render(): void;
+    start(): void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    hitTest(stageX: number, stageY: number): ActorHit | null;
+    hitTestAll(stageX: number, stageY: number): readonly ActorHit[];
+    addEventListener(type: "pointerdown" | "pointermove" | "pointerup", listener: (event: StagePointerEvent) => void): void;
+    removeEventListener(type: "pointerdown" | "pointermove" | "pointerup", listener: (event: StagePointerEvent) => void): void;
+    destroy(): void;
+    pointerTracking: PointerTrackingPolicy;
+}
+
+/**
+ * `@doki-land/live2d-core` — types, events, session contracts.
+ */
+
+declare const LIVE2D_CORE_VERSION: "0.0.0";
+
+export { type ActorHit, type ActorTransform, type AssetKey, type AssetResolver, type CreateActorOptions, type CreateLive2dStageOptions, DEFAULT_ACTOR_TRANSFORM, type DrawableProgram, EventEmitter, type ExpressionDefinition, FrameBlendMode, type FrameDrawable, type FrameProfile, type FrameSnapshot, type HitAreaDefinition, type InternalModel, LIVE2D_CORE_VERSION, type Live2DEventMap, type Live2DEventName, type Live2DListener, type Live2DSession, type Live2dActor, type Live2dStage, type LoadProgress, type LoadProgressStage, type ModelFormat, type ModelInstance, type ModelProgram, type ModelSettings, type ModelSource, type MotionDefinition, type ParameterProgram, type PointerTrackingMode, type PointerTrackingPolicy, type SessionPhase, type SessionState, type StagePointerEvent, type StageUpdateMode, createSessionStub, detectModelSettingsFormat, modelSourceUrl };

package/dist/index.js

@@ -0,0 +1,131 @@
+// src/contracts.ts
+function modelSourceUrl(source) {
+  if (typeof source === "string") return source;
+  if (source.kind === "url") return source.url;
+  if (source.kind === "npm") {
+    const path = source.path.replace(/^\/+/, "");
+    return `npm:${source.package}/${path}`;
+  }
+  return source.baseUrl;
+}
+
+// src/detect-format.ts
+function detectModelSettingsFormat(json) {
+  if (!json || typeof json !== "object") return null;
+  const o = json;
+  const fileRefs = o.FileReferences;
+  if (fileRefs && typeof fileRefs === "object") {
+    const moc = fileRefs.Moc;
+    if (typeof moc === "string") {
+      const lower = moc.toLowerCase();
+      if (lower.endsWith(".moc3") || lower.endsWith(".program.json")) {
+        return "moc3";
+      }
+      if (lower.endsWith(".moc")) {
+        return "moc2";
+      }
+      return "moc3";
+    }
+  }
+  if (typeof o.model === "string" && Array.isArray(o.textures)) {
+    return "moc2";
+  }
+  return null;
+}
+
+// src/events.ts
+var EventEmitter = class {
+  #listeners = /* @__PURE__ */ new Map();
+  on(event, listener) {
+    const set = this.#listeners.get(event) ?? /* @__PURE__ */ new Set();
+    set.add(listener);
+    this.#listeners.set(event, set);
+    return () => this.off(event, listener);
+  }
+  off(event, listener) {
+    this.#listeners.get(event)?.delete(listener);
+  }
+  emit(event, payload) {
+    for (const listener of this.#listeners.get(event) ?? []) {
+      listener(payload);
+    }
+  }
+  clear() {
+    this.#listeners.clear();
+  }
+};
+
+// src/frame.ts
+var FrameBlendMode = {
+  Normal: 0,
+  Additive: 1,
+  Multiplicative: 2
+};
+
+// src/session.ts
+function createSessionStub() {
+  let canvas = null;
+  let model = null;
+  const events = new EventEmitter();
+  let generation = 0;
+  return {
+    events,
+    get model() {
+      return model;
+    },
+    get state() {
+      return {
+        phase: model ? "live" : canvas ? "ready" : "idle",
+        lastError: null,
+        generation
+      };
+    },
+    mount(target) {
+      canvas = target;
+      generation += 1;
+    },
+    async loadModel(_source, _resolver) {
+      void canvas;
+      void _resolver;
+      throw new Error(
+        "@doki-land/live2d-core: loadModel is provided by @doki-land/live2d facade"
+      );
+    },
+    captureFrame() {
+      return null;
+    },
+    update(_deltaTimeSeconds) {
+      if (!model) return;
+    },
+    hitTest(_x, _y) {
+      return null;
+    },
+    destroy() {
+      model = null;
+      canvas = null;
+      generation += 1;
+      events.clear();
+    }
+  };
+}
+
+// src/stage.ts
+var DEFAULT_ACTOR_TRANSFORM = {
+  x: 0.5,
+  y: 1,
+  scale: 1,
+  anchorX: 0.5,
+  anchorY: 1
+};
+
+// src/index.ts
+var LIVE2D_CORE_VERSION = "0.0.0";
+export {
+  DEFAULT_ACTOR_TRANSFORM,
+  EventEmitter,
+  FrameBlendMode,
+  LIVE2D_CORE_VERSION,
+  createSessionStub,
+  detectModelSettingsFormat,
+  modelSourceUrl
+};

package/package.json

@@ -1 +1,42 @@
-{"name":"@doki-land/live2d-core","version":"0.0.0","description":"placeholder","license":"MIT","private":false}
+{
+  "name": "@doki-land/live2d-core",
+  "version": "0.0.12",
+  "description": "Live2D types, events, and session contracts",
+  "type": "module",
+  "license": "MIT",
+  "author": "Doki Land",
+  "keywords": [
+    "live2d",
+    "doki-land"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/live2d.ts.git"
+  }
+}

package/src/contracts.ts

@@ -0,0 +1,63 @@
+/**
+ * Internal loading / session contracts shared across packages.
+ * Format decode and GPU details stay in live2d-renderer.
+ */
+
+/** How the host names a model settings document. */
+export type ModelSource =
+    | string
+    | { readonly kind: "url"; readonly url: string }
+    | {
+          readonly kind: "json";
+          readonly json: unknown;
+          readonly baseUrl: string;
+      }
+    | {
+          readonly kind: "npm";
+          /** Package name, optionally with `@version` (e.g. `live2d-widget-model-hijiki@1.0.5`). */
+          readonly package: string;
+          /** Path inside the package to model JSON. */
+          readonly path: string;
+          /** Optional CDN base; default is applied by the loader. */
+          readonly cdnBase?: string;
+      };
+
+export function modelSourceUrl(source: ModelSource): string {
+    if (typeof source === "string") return source;
+    if (source.kind === "url") return source.url;
+    if (source.kind === "npm") {
+        const path = source.path.replace(/^\/+/, "");
+        return `npm:${source.package}/${path}`;
+    }
+    return source.baseUrl;
+}
+
+/** Relative asset key as declared in settings (moc, texture, motion, …). */
+export type AssetKey = string;
+
+/** Resolve and fetch assets relative to a model settings URL. */
+export interface AssetResolver {
+    readonly baseUrl: string;
+
+    resolve(key: AssetKey): string;
+
+    fetchJson(key: AssetKey): Promise<unknown>;
+
+    fetchBytes(key: AssetKey): Promise<ArrayBuffer>;
+}
+
+/** Session lifecycle (facade state machine). */
+export type SessionPhase =
+    | "idle"
+    | "mounting"
+    | "ready"
+    | "loading"
+    | "live"
+    | "error"
+    | "destroyed";
+
+export interface SessionState {
+    readonly phase: SessionPhase;
+    readonly lastError: unknown | null;
+    readonly generation: number;
+}

package/src/detect-format.ts

@@ -0,0 +1,31 @@
+/**
+ * Settings JSON format detection (moc2 vs moc3).
+ * Shared by loader normalize and renderer backends — keep binary peek in renderer.
+ */
+
+import type { ModelFormat } from "./model.js";
+
+/** Detect moc2 vs moc3 from model settings JSON shape. Returns null if unknown. */
+export function detectModelSettingsFormat(json: unknown): ModelFormat | null {
+    if (!json || typeof json !== "object") return null;
+    const o = json as Record<string, unknown>;
+    const fileRefs = o.FileReferences;
+    if (fileRefs && typeof fileRefs === "object") {
+        const moc = (fileRefs as Record<string, unknown>).Moc;
+        if (typeof moc === "string") {
+            const lower = moc.toLowerCase();
+            if (lower.endsWith(".moc3") || lower.endsWith(".program.json")) {
+                return "moc3";
+            }
+            if (lower.endsWith(".moc")) {
+                return "moc2";
+            }
+            // Cubism 3 settings without a recognized extension still count as moc3.
+            return "moc3";
+        }
+    }
+    if (typeof o.model === "string" && Array.isArray(o.textures)) {
+        return "moc2";
+    }
+    return null;
+}

package/src/events.ts

@@ -0,0 +1,92 @@
+/** Load pipeline stage for progress UI. */
+export type LoadProgressStage =
+    | "mounting"
+    | "resolve"
+    | "settings"
+    | "moc"
+    | "textures"
+    | "decode"
+    | "ready";
+
+export interface LoadProgress {
+    readonly stage: LoadProgressStage;
+    /** Overall 0..1 */
+    readonly progress: number;
+    readonly detail?: string;
+    readonly bytesLoaded?: number;
+    readonly bytesTotal?: number | null;
+}
+
+/** Per-frame timing / mesh cost for Status / profiler UIs. */
+export interface FrameProfile {
+    /** Instantaneous FPS from wall dt (0 if first frame). */
+    readonly fps: number;
+    /** EMA-smoothed FPS for readable UI. */
+    readonly fpsSmooth: number;
+    /** Whole `update()` wall time in ms. */
+    readonly frameMs: number;
+    /** `updateModel` + `getDrawables` in ms. */
+    readonly evaluateMs: number;
+    /** `beginFrame` + `draw` + `endFrame` in ms. */
+    readonly drawMs: number;
+    readonly drawableCount: number;
+    /** Sum of drawable vertex counts (xy pairs). */
+    readonly vertexCount: number;
+    /** Sum of drawable index counts. */
+    readonly indexCount: number;
+}
+
+/** Minimal event bus used by sessions and loaders. */
+export type Live2DEventMap = {
+    ready: { modelId: string };
+    error: { error: unknown };
+    progress: LoadProgress;
+    /** Fired after each successful `update()` while live. */
+    profile: FrameProfile;
+    hit: { area: string; x: number; y: number };
+    "motion:start": { group: string; index: number; slot: string };
+    "motion:finish": { group: string; index: number; slot: string };
+    phase: { phase: string; generation: number };
+};
+
+export type Live2DEventName = keyof Live2DEventMap;
+
+export type Live2DListener<K extends Live2DEventName> = (
+    payload: Live2DEventMap[K],
+) => void;
+
+export class EventEmitter {
+    #listeners = new Map<string, Set<(payload: unknown) => void>>();
+
+    on<K extends Live2DEventName>(
+        event: K,
+        listener: Live2DListener<K>,
+    ): () => void {
+        const set = this.#listeners.get(event) ?? new Set();
+        set.add(listener as (payload: unknown) => void);
+        this.#listeners.set(event, set);
+        return () => this.off(event, listener);
+    }
+
+    off<K extends Live2DEventName>(
+        event: K,
+        listener: Live2DListener<K>,
+    ): void {
+        this.#listeners
+            .get(event)
+            ?.delete(listener as (payload: unknown) => void);
+    }
+
+    emit<K extends Live2DEventName>(
+        event: K,
+        payload: Live2DEventMap[K],
+    ): void {
+        for (const listener of this.#listeners.get(event) ?? []) {
+            listener(payload);
+        }
+    }
+
+    clear(): void {
+        this.#listeners.clear();
+    }
+}

package/src/frame.ts

@@ -0,0 +1,35 @@
+/**
+ * CPU frame output — format-agnostic mesh list ready for any RenderDevice.
+ */
+
+/** Blend modes aligned with renderer DrawableMesh. */
+export const FrameBlendMode = {
+    Normal: 0,
+    Additive: 1,
+    Multiplicative: 2,
+} as const;
+
+export type FrameBlendMode =
+    (typeof FrameBlendMode)[keyof typeof FrameBlendMode];
+
+/** One drawable after CPU deform for a single frame. */
+export interface FrameDrawable {
+    readonly index: number;
+    readonly textureIndex: number;
+    /** Interleaved x,y in model space. */
+    readonly positions: Float32Array;
+    readonly uvs: Float32Array;
+    readonly indices: Uint16Array;
+    readonly opacity: number;
+    readonly blendMode: FrameBlendMode;
+    readonly renderOrder: number;
+    readonly visible: boolean;
+    readonly invertedMask: boolean;
+    readonly maskIndices: readonly number[];
+}
+
+/** Immutable CPU snapshot consumed by GPU backends or golden tests. */
+export interface FrameSnapshot {
+    readonly timeSeconds: number;
+    readonly drawables: readonly FrameDrawable[];
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+/**
+ * `@doki-land/live2d-core` — types, events, session contracts.
+ */
+
+export type {
+    AssetKey,
+    AssetResolver,
+    ModelSource,
+    SessionPhase,
+    SessionState,
+} from "./contracts.js";
+export { modelSourceUrl } from "./contracts.js";
+export { detectModelSettingsFormat } from "./detect-format.js";
+export {
+    EventEmitter,
+    type FrameProfile,
+    type Live2DEventMap,
+    type Live2DEventName,
+    type Live2DListener,
+    type LoadProgress,
+    type LoadProgressStage,
+} from "./events.js";
+export {
+    FrameBlendMode,
+    type FrameDrawable,
+    type FrameSnapshot,
+} from "./frame.js";
+export type {
+    ExpressionDefinition,
+    HitAreaDefinition,
+    InternalModel,
+    ModelFormat,
+    ModelSettings,
+    MotionDefinition,
+} from "./model.js";
+export type {
+    DrawableProgram,
+    ModelInstance,
+    ModelProgram,
+    ParameterProgram,
+} from "./program.js";
+export {
+    createSessionStub,
+    type Live2DSession,
+} from "./session.js";
+export type {
+    ActorHit,
+    ActorTransform,
+    CreateActorOptions,
+    CreateLive2dStageOptions,
+    Live2dActor,
+    Live2dStage,
+    PointerTrackingMode,
+    PointerTrackingPolicy,
+    StagePointerEvent,
+    StageUpdateMode,
+} from "./stage.js";
+export { DEFAULT_ACTOR_TRANSFORM } from "./stage.js";
+
+export const LIVE2D_CORE_VERSION = "0.0.0" as const;

package/src/model.ts

@@ -0,0 +1,41 @@
+/** Model binary family (file extension / settings shape). */
+export type ModelFormat = "moc2" | "moc3";
+
+/** Normalized, format-agnostic model settings. */
+export interface ModelSettings {
+    format: ModelFormat;
+    url: string;
+    name?: string;
+    moc: string;
+    textures: string[];
+    motionGroups: Record<string, MotionDefinition[]>;
+    expressions: ExpressionDefinition[];
+    physics?: string;
+    pose?: string;
+    hitAreas: HitAreaDefinition[];
+    layout?: Record<string, number>;
+}
+
+export interface MotionDefinition {
+    file: string;
+    sound?: string;
+    fadeInTime?: number;
+    fadeOutTime?: number;
+}
+
+export interface ExpressionDefinition {
+    name: string;
+    file: string;
+}
+
+export interface HitAreaDefinition {
+    name: string;
+    id: string;
+}
+
+/** Opaque in-memory model handle. */
+export interface InternalModel {
+    readonly id: string;
+    readonly settings: ModelSettings;
+    readonly format: ModelFormat;
+}

package/src/program.ts

@@ -0,0 +1,50 @@
+/**
+ * CPU model program / instance shapes (format adapters fill these).
+ */
+
+export interface ParameterProgram {
+    readonly id: string;
+    readonly min: number;
+    readonly max: number;
+    readonly defaultValue: number;
+}
+
+export interface DrawableProgram {
+    readonly index: number;
+    readonly textureIndex: number;
+    /** Rest-pose x,y pairs. */
+    readonly positions: Float32Array;
+    readonly uvs: Float32Array;
+    readonly indices: Uint16Array;
+    readonly opacity: number;
+    readonly renderOrder: number;
+    /** {@link FrameBlendMode} value. */
+    readonly blendMode: number;
+    readonly invertedMask: boolean;
+    /** Indices into `ModelProgram.drawables` used as clipping masks. */
+    readonly maskIndices: readonly number[];
+    readonly visible: boolean;
+    /**
+     * Optional linear deform driven by one parameter.
+     * `deltas[i] = positions_at_max[i] - rest[i]`.
+     */
+    readonly deformParamIndex: number;
+    readonly deformDeltas: Float32Array | null;
+}
+
+/** Static topology + deform tables after decode. */
+export interface ModelProgram {
+    readonly format: "moc2" | "moc3";
+    /** Codec tag, e.g. `cpu-program` or `moc3`. */
+    readonly codec: string;
+    readonly parameters: readonly ParameterProgram[];
+    readonly drawables: readonly DrawableProgram[];
+}
+
+/** Mutable runtime values over a ModelProgram. */
+export interface ModelInstance {
+    readonly program: ModelProgram;
+    /** Parallel to program.parameters. */
+    readonly parameterValues: Float32Array;
+    timeSeconds: number;
+}

package/src/session.ts

@@ -0,0 +1,78 @@
+import type { AssetResolver, ModelSource, SessionState } from "./contracts.js";
+import { EventEmitter } from "./events.js";
+import type { FrameSnapshot } from "./frame.js";
+import type { InternalModel } from "./model.js";
+
+/** High-level runtime session for one mounted surface. */
+export interface Live2DSession {
+    readonly events: EventEmitter;
+    readonly model: InternalModel | null;
+    readonly state: SessionState;
+
+    mount(canvas: HTMLCanvasElement): void;
+
+    loadModel(
+        source: ModelSource,
+        resolver?: AssetResolver,
+    ): Promise<InternalModel>;
+
+    /** Latest CPU frame after update, or null if no model. */
+    captureFrame(): FrameSnapshot | null;
+
+    update(deltaTimeSeconds: number): void;
+
+    hitTest(x: number, y: number): string | null;
+
+    destroy(): void;
+}
+
+export function createSessionStub(): Live2DSession {
+    let canvas: HTMLCanvasElement | null = null;
+    let model: InternalModel | null = null;
+    const events = new EventEmitter();
+    let generation = 0;
+
+    return {
+        events,
+        get model() {
+            return model;
+        },
+        get state() {
+            return {
+                phase: model
+                    ? ("live" as const)
+                    : canvas
+                      ? ("ready" as const)
+                      : ("idle" as const),
+                lastError: null,
+                generation,
+            };
+        },
+        mount(target) {
+            canvas = target;
+            generation += 1;
+        },
+        async loadModel(_source, _resolver) {
+            void canvas;
+            void _resolver;
+            throw new Error(
+                "@doki-land/live2d-core: loadModel is provided by @doki-land/live2d facade",
+            );
+        },
+        captureFrame() {
+            return null;
+        },
+        update(_deltaTimeSeconds) {
+            if (!model) return;
+        },
+        hitTest(_x, _y) {
+            return null;
+        },
+        destroy() {
+            model = null;
+            canvas = null;
+            generation += 1;
+            events.clear();
+        },
+    };
+}

package/src/stage.ts

@@ -0,0 +1,147 @@
+import type { InternalModel } from "./model.js";
+
+/** Normalized stage placement for one actor (0,0) top-left → (1,1) bottom-right. */
+export interface ActorTransform {
+    /** Anchor point X in stage space. */
+    x: number;
+    /** Anchor point Y in stage space. */
+    y: number;
+    /** Uniform scale; ignored when `scaleX` / `scaleY` are set. */
+    scale?: number;
+    scaleX?: number;
+    scaleY?: number;
+    /** Radians, counter-clockwise. */
+    rotation?: number;
+    /** Horizontal anchor within the model bounds (0 = left, 1 = right). */
+    anchorX?: number;
+    /** Vertical anchor within the model bounds (0 = top, 1 = bottom in stage space). */
+    anchorY?: number;
+}
+
+export const DEFAULT_ACTOR_TRANSFORM: Readonly<ActorTransform> = {
+    x: 0.5,
+    y: 1,
+    scale: 1,
+    anchorX: 0.5,
+    anchorY: 1,
+};
+
+export type PointerTrackingMode =
+    | "all"
+    | "focused"
+    | "hovered"
+    | "nearest"
+    | "none"
+    | "custom";
+
+export interface PointerTrackingPolicy {
+    mode: PointerTrackingMode;
+    /** Used when `mode` is `custom`. */
+    targetActorId?: string;
+}
+
+export interface CreateActorOptions {
+    id?: string;
+    transform?: Partial<ActorTransform>;
+    layer?: string;
+    order?: number;
+    visible?: boolean;
+    opacity?: number;
+}
+
+export interface ActorHit {
+    readonly actor: Live2dActor;
+    readonly actorId: string;
+    readonly area: string;
+    readonly drawableIndex: number;
+    readonly stageX: number;
+    readonly stageY: number;
+    readonly localX: number;
+    readonly localY: number;
+}
+
+export interface StagePointerEvent {
+    readonly actor: Live2dActor | null;
+    readonly actorId: string | null;
+    readonly area: string | null;
+    readonly stageX: number;
+    readonly stageY: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly hit: ActorHit | null;
+}
+
+export type StageUpdateMode = "auto" | "manual";
+
+export interface CreateLive2dStageOptions {
+    updateMode?: StageUpdateMode;
+}
+
+/** Read-only actor surface exposed by the stage. */
+export interface Live2dActor {
+    readonly id: string;
+    readonly model: InternalModel | null;
+    readonly visible: boolean;
+    readonly opacity: number;
+    readonly layer: string;
+    readonly order: number;
+    readonly creationIndex: number;
+
+    getTransform(): ActorTransform;
+
+    setTransform(patch: Partial<ActorTransform>): void;
+
+    load(
+        source: import("./contracts.js").ModelSource,
+        resolver?: import("./contracts.js").AssetResolver,
+    ): Promise<InternalModel>;
+
+    setParameter(id: string, value: number): void;
+
+    lookAt(stageX: number, stageY: number): void;
+
+    destroy(): void;
+}
+
+/** Multi-character stage owning one canvas surface and shared renderer. */
+export interface Live2dStage {
+    readonly actors: readonly Live2dActor[];
+
+    mount(canvas: HTMLCanvasElement): Promise<void>;
+
+    createActor(options?: CreateActorOptions): Live2dActor;
+
+    removeActor(actor: Live2dActor | string): void;
+
+    defineLayers(layers: readonly string[]): void;
+
+    update(deltaTimeSeconds: number): void;
+
+    render(): void;
+
+    start(): void;
+
+    pause(): void;
+
+    resume(): void;
+
+    stop(): void;
+
+    hitTest(stageX: number, stageY: number): ActorHit | null;
+
+    hitTestAll(stageX: number, stageY: number): readonly ActorHit[];
+
+    addEventListener(
+        type: "pointerdown" | "pointermove" | "pointerup",
+        listener: (event: StagePointerEvent) => void,
+    ): void;
+
+    removeEventListener(
+        type: "pointerdown" | "pointermove" | "pointerup",
+        listener: (event: StagePointerEvent) => void,
+    ): void;
+
+    destroy(): void;
+
+    pointerTracking: PointerTrackingPolicy;
+}