@doki-land/live2d 0.0.15 → 0.0.17

package/README.md

@@ -2,7 +2,8 @@
 
 The public runtime facade for browser-native Live2D rendering.
 
-Use this package in browser games, game-engine integrations, interactive content, model tools, and custom webpage experiences. It composes the default loader, MOC runtimes, and rendering backends behind one small API.
+Use this package in browser games, game-engine integrations, interactive content, model tools, and custom webpage
+experiences. It composes the default loader, MOC runtimes, and rendering backends behind one small API.
 
 ## ✨ Features
 
@@ -24,19 +25,28 @@ pnpm add @doki-land/live2d
 
 The implementation packages are installed transitively. Most applications should not depend on them directly.
 
+## 🧭 Source Layout
+
+```text
+src/facade/    createLive2D() — default stage + single actor
+src/motion/    motion3 parse, curves, MotionPlayer
+src/stage/     Live2dStage, actors, asset registry, transforms
+src/reexports/ optional subpath exports for core / loader / renderer
+```
+
 ## 🚀 Quick Start
 
 ```ts
-import { createLive2D } from "@doki-land/live2d";
+import {createLive2D} from "@doki-land/live2d";
 
 const canvas = document.querySelector<HTMLCanvasElement>("#live2d");
 
 if (!canvas) {
-  throw new Error("Missing Live2D canvas");
+    throw new Error("Missing Live2D canvas");
 }
 
 const runtime = createLive2D({
-  prefer: ["webgpu", "webgl2", "canvas2d"],
+    prefer: ["webgpu", "webgl2", "canvas2d"],
 });
 
 runtime.mount(canvas);
@@ -45,9 +55,9 @@ await runtime.loadModel("/models/character.model3.json");
 let previous = performance.now();
 
 function frame(now: number) {
-  runtime.update((now - previous) / 1000);
-  previous = now;
-  requestAnimationFrame(frame);
+    runtime.update((now - previous) / 1000);
+    previous = now;
+    requestAnimationFrame(frame);
 }
 
 requestAnimationFrame(frame);
@@ -59,11 +69,12 @@ The runtime does not require ownership of `requestAnimationFrame`. Drive it from
 
 ```ts
 engine.onUpdate((deltaTime) => {
-  runtime.update(deltaTime);
+    runtime.update(deltaTime);
 });
 ```
 
-The delta is expressed in seconds. Keep the value bounded after tab suspension or long pauses to avoid unstable animation and physics once those systems are enabled.
+The delta is expressed in seconds. Keep the value bounded after tab suspension or long pauses to avoid unstable
+animation and physics once those systems are enabled.
 
 ## 📥 Loading Models
 
@@ -71,19 +82,19 @@ The delta is expressed in seconds. Keep the value bounded after tab suspension o
 await runtime.loadModel("/models/actor.model3.json");
 
 await runtime.loadModel(
-  "https://cdn.example.com/models/actor.model3.json",
+    "https://cdn.example.com/models/actor.model3.json",
 );
 
 await runtime.loadModel(
-  "npm:live2d-widget-model-hijiki@1.0.5/assets/hijiki.model.json",
+    "npm:live2d-widget-model-hijiki@1.0.5/assets/hijiki.model.json",
 );
 ```
 
 Listen for progress when presenting a loading interface:
 
 ```ts
-runtime.events.on("progress", ({ stage, progress, detail }) => {
-  console.log(stage, Math.round(progress * 100), detail);
+runtime.events.on("progress", ({stage, progress, detail}) => {
+    console.log(stage, Math.round(progress * 100), detail);
 });
 ```
 
@@ -95,8 +106,8 @@ Remote servers must allow cross-origin access to settings, model binaries, and t
 runtime.setParameter("PARAM_ANGLE_X", 15);
 
 const angleX = runtime
-  .listParameters()
-  .find((parameter) => parameter.id === "PARAM_ANGLE_X");
+    .listParameters()
+    .find((parameter) => parameter.id === "PARAM_ANGLE_X");
 
 console.log(angleX);
 ```
@@ -111,27 +122,29 @@ Parameter availability and ranges belong to the loaded model. Do not assume ever
 const area = runtime.hitTest(modelX, modelY);
 
 if (area) {
-  console.log("Hit", area);
+    console.log("Hit", area);
 }
 ```
 
-Current fallback hit testing can identify visible drawables. Semantic names such as `Head` or `Body` require corresponding model metadata and runtime support.
+Current fallback hit testing can identify visible drawables. Semantic names such as `Head` or `Body` require
+corresponding model metadata and runtime support.
 
 ## 📊 Frame Profiling
 
 ```ts
 runtime.events.on("profile", (profile) => {
-  console.log({
-    fps: profile.fpsSmooth,
-    frameMs: profile.frameMs,
-    evaluateMs: profile.evaluateMs,
-    drawMs: profile.drawMs,
-    drawables: profile.drawableCount,
-  });
+    console.log({
+        fps: profile.fpsSmooth,
+        frameMs: profile.frameMs,
+        evaluateMs: profile.evaluateMs,
+        drawMs: profile.drawMs,
+        drawables: profile.drawableCount,
+    });
 });
 ```
 
-These timings are runtime-side measurements. Use browser GPU profiling when diagnosing shader, mask, upload, or device scheduling costs.
+These timings are runtime-side measurements. Use browser GPU profiling when diagnosing shader, mask, upload, or device
+scheduling costs.
 
 ## 🧩 Custom Pipeline
 
@@ -139,12 +152,13 @@ Advanced applications can provide a renderer or model backends:
 
 ```ts
 const runtime = createLive2D({
-  renderer: customRenderer,
-  backends: [customBackend],
+    renderer: customRenderer,
+    backends: [customBackend],
 });
 ```
 
-Custom implementations must preserve the contracts exported by the renderer package. Avoid moving format or renderer logic into application adapters.
+Custom implementations must preserve the contracts exported by the renderer package. Avoid moving format or renderer
+logic into application adapters.
 
 ## 🧹 Lifecycle
 
@@ -152,7 +166,8 @@ Custom implementations must preserve the contracts exported by the renderer pack
 runtime.destroy();
 ```
 
-Destroy the runtime when its canvas or host scene is permanently removed. This releases model state, textures, draw passes, event listeners owned by the runtime, and graphics resources owned by the selected renderer.
+Destroy the runtime when its canvas or host scene is permanently removed. This releases model state, textures, draw
+passes, event listeners owned by the runtime, and graphics resources owned by the selected renderer.
 
 ## ⚡ Performance Notes
 
@@ -160,7 +175,8 @@ Destroy the runtime when its canvas or host scene is permanently removed. This r
 - Keep canvas backing dimensions intentional; CSS size alone does not limit GPU pixel work.
 - Prefer an engine-owned loop when integrating with a game.
 - Avoid repeatedly enumerating parameters in a hot loop.
-- Measure the complete frame path before attributing a bottleneck to TypeScript, WebAssembly, or a specific graphics API.
+- Measure the complete frame path before attributing a bottleneck to TypeScript, WebAssembly, or a specific graphics
+  API.
 
 ## 🧪 Development
 
@@ -171,12 +187,38 @@ pnpm typecheck
 pnpm --filter @doki-land/live2d build
 ```
 
-Changes to the facade should include tests for state transitions, cancellation, events, and resource cleanup where applicable.
+Changes to the facade should include tests for state transitions, cancellation, events, and resource cleanup where
+applicable.
 
 ## 🤝 Contributing
 
-Keep the facade small. Model-format behavior belongs in `@doki-land/live2d-renderer`, source resolution belongs in `@doki-land/live2d-loader`, and webpage chrome belongs in `@doki-land/live2d-widget`.
+### Package ownership
+
+- Keep the facade small and host-independent.
+- Put model-format behavior in `@doki-land/live2d-renderer`.
+- Put source resolution in `@doki-land/live2d-loader`.
+- Put webpage chrome in `@doki-land/live2d-widget`.
+- Include tests for state transitions, cancellation, events, and resource cleanup where applicable.
 
 ## 📄 License
 
-See the repository license. Model and artwork licenses are separate from the runtime license.
+### Implementation independence
+
+- This package composes an independently developed clean-room runtime.
+- It does not load, link against, wrap, translate, port, or derive its implementation from an official Cubism SDK or
+  Core binary.
+- Compatible model support is an interoperability goal, not evidence of a shared implementation, endorsement,
+  affiliation, sponsorship, or employment relationship.
+- The project and its contributors are independent and do not act on behalf of the official Cubism SDK vendor.
+
+### Contribution boundary
+
+- Do not submit official SDK or shader source, disassembly-derived code, mechanically translated implementation code, or
+  changes that require an official runtime.
+- Support compatibility-sensitive work with public format facts, neutral fixtures, reproducible independent
+  observations, or independently authored technical rationale.
+
+### Terms
+
+- See the repository license for source-code terms.
+- Model and artwork licenses are separate from the runtime license.

package/dist/index.d.ts

@@ -367,11 +367,11 @@ interface Live2DRuntime extends Live2DSession {
 declare function createLive2D(options?: CreateLive2DOptions): Live2DRuntime;
 
 /**
- * Map canvas focus (-1..1, Y-up) onto standard Cubism drag parameters.
+ * Map canvas focus (-1..1, Y-up) onto commonly used model parameter IDs.
  *
- * Matches the Cubism sample / community widget weights:
- * ANGLE_X/Y full range, ANGLE_Z = -dragX*dragY, BODY_ANGLE_X, EYE_BALL_*.
- * Missing ids on a given model are skipped.
+ * ANGLE_X/Y use the full declared range, ANGLE_Z combines both axes, and body
+ * and eye parameters receive the corresponding normalized axis. Parameters not
+ * declared by a model are skipped.
  */
 declare function focusParameterUpdates(parameters: readonly ParameterBinding[], dragX: number, dragY: number): Array<{
     id: string;
@@ -381,6 +381,12 @@ declare function focusParameterUpdates(parameters: readonly ParameterBinding[],
 /**
  * `@doki-land/live2d` — public facade.
  *
+ * Layout:
+ * - `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";
  * ```

package/dist/index.js

@@ -20,14 +20,14 @@ import {
   serializeCpuProgram
 } from "@doki-land/live2d-renderer";
 
-// src/create-live2d.ts
+// src/facade/create-live2d.ts
 import {
   createMoc2Backend as createMoc2Backend2,
   createMoc3Backend as createMoc3Backend2,
   createRenderer as createRenderer2
 } from "@doki-land/live2d-renderer";
 
-// src/focus.ts
+// src/stage/assets/focus.ts
 function focusParameterUpdates(parameters, dragX, dragY) {
   const byId = new Map(parameters.map((p) => [p.id, p]));
   const x = clampUnit(dragX);
@@ -1195,7 +1195,7 @@ import {
   selectModelBackend
 } from "@doki-land/live2d-renderer";
 
-// src/load-textures.ts
+// src/stage/assets/load-textures.ts
 function guessMime(path) {
   const lower = path.toLowerCase();
   if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
@@ -1816,7 +1816,7 @@ function createLive2dStage(options) {
   return new Live2dStageImpl(options);
 }
 
-// src/create-live2d.ts
+// src/facade/create-live2d.ts
 function createLive2D(options = {}) {
   const backends = options.backends ?? [
     createMoc2Backend2(),

package/package.json

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

package/src/{create-live2d.ts → facade/create-live2d.ts}

@@ -3,22 +3,22 @@ import {
     createMoc3Backend,
     createRenderer,
 } from "@doki-land/live2d-renderer";
-import { allocateActorId } from "./stage/actor.js";
+import { allocateActorId } from "../stage/actor.js";
 import {
     type CreateLive2DOptions,
     createSingleActorFacade,
     type Live2DRuntime,
-} from "./stage/single-facade.js";
-import { createLive2dStage } from "./stage/stage.js";
+} from "../stage/single-facade.js";
+import { createLive2dStage } from "../stage/stage.js";
 
 export type {
     CreateLive2DOptions,
     Live2DRuntime,
-} from "./stage/single-facade.js";
+} from "../stage/single-facade.js";
 export {
     MotionPriority,
     type PlayMotionOptions,
-} from "./stage/single-facade.js";
+} from "../stage/single-facade.js";
 
 /** Wire moc backends and a renderer into one single-actor session. */
 export function createLive2D(options: CreateLive2DOptions = {}): Live2DRuntime {
@@ -31,9 +31,9 @@ export function createLive2D(options: CreateLive2DOptions = {}): Live2DRuntime {
         renderer:
             options.renderer ?? createRenderer({ prefer: options.prefer }),
         updateMode: options.updateMode ?? "manual",
-    }) as import("./stage/stage.js").Live2dStageImpl;
+    }) as import("../stage/stage.js").Live2dStageImpl;
     const actor = stage.createActor({
         id: allocateActorId("default"),
-    }) as import("./stage/actor.js").Live2dActorImpl;
+    }) as import("../stage/actor.js").Live2dActorImpl;
     return createSingleActorFacade(stage, actor, backends);
 }

package/src/index.ts

@@ -1,6 +1,12 @@
 /**
  * `@doki-land/live2d` — public facade.
  *
+ * Layout:
+ * - `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";
  * ```
@@ -66,8 +72,8 @@ export {
     type Live2DRuntime,
     MotionPriority,
     type PlayMotionOptions,
-} from "./create-live2d.js";
-export { focusParameterUpdates } from "./focus.js";
+} from "./facade/create-live2d.js";
+export { focusParameterUpdates } from "./stage/assets/focus.js";
 export {
     blendMotionLayers,
     evaluateCurve,

package/src/stage/actor.ts

@@ -8,7 +8,7 @@ import type {
     PlayMotionActorOptions,
 } from "@doki-land/live2d-core";
 import type { DrawableMesh, Renderer } from "@doki-land/live2d-renderer";
-import { focusParameterUpdates } from "../focus.js";
+import { focusParameterUpdates } from "./assets/focus.js";
 import type { PlayMotionOptions } from "../motion/index.js";
 import { ActorModelSlot } from "./actor-model-slot.js";
 import type { ModelAssetRegistry } from "./model-asset-registry.js";

package/src/{focus.ts → stage/assets/focus.ts}

@@ -1,11 +1,11 @@
 import type { ParameterBinding } from "@doki-land/live2d-renderer";
 
 /**
- * Map canvas focus (-1..1, Y-up) onto standard Cubism drag parameters.
+ * Map canvas focus (-1..1, Y-up) onto commonly used model parameter IDs.
  *
- * Matches the Cubism sample / community widget weights:
- * ANGLE_X/Y full range, ANGLE_Z = -dragX*dragY, BODY_ANGLE_X, EYE_BALL_*.
- * Missing ids on a given model are skipped.
+ * ANGLE_X/Y use the full declared range, ANGLE_Z combines both axes, and body
+ * and eye parameters receive the corresponding normalized axis. Parameters not
+ * declared by a model are skipped.
  */
 export function focusParameterUpdates(
     parameters: readonly ParameterBinding[],
@@ -26,8 +26,7 @@ export function focusParameterUpdates(
     set("PARAM_ANGLE_X", x);
     set("PARAM_ANGLE_Y", y);
     set("PARAM_ANGLE_Z", clampUnit(x * y * -1));
-    // Official sample uses dragX*10 vs ANGLE's *30; BODY range is typically ±10,
-    // so full-range normalized drag still matches that relative weight.
+    // Each binding maps normalized input through its own declared range.
     set("PARAM_BODY_ANGLE_X", x);
     set("PARAM_BODY_ANGLE_Y", y);
     set("PARAM_EYE_BALL_X", x);

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

@@ -23,7 +23,7 @@ import {
     compileSharedModelCompile,
     selectModelBackend,
 } from "@doki-land/live2d-renderer";
-import { loadTextureData, releaseTextureData } from "../load-textures.js";
+import { loadTextureData, releaseTextureData } from "./assets/load-textures.js";
 import type { Motion3Clip } from "../motion/index.js";
 import { resolveModelAssetKey } from "./model-asset-key.js";