@doki-land/live2d 0.0.16 → 0.0.17

package/README.md

@@ -25,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);
@@ -46,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);
@@ -60,7 +69,7 @@ The runtime does not require ownership of `requestAnimationFrame`. Drive it from
 
 ```ts
 engine.onUpdate((deltaTime) => {
-  runtime.update(deltaTime);
+    runtime.update(deltaTime);
 });
 ```
 
@@ -73,11 +82,11 @@ animation and physics once those systems are enabled.
 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",
 );
 ```
 
@@ -97,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);
 ```
@@ -113,7 +122,7 @@ 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);
 }
 ```
 
@@ -143,8 +152,8 @@ Advanced applications can provide a renderer or model backends:
 
 ```ts
 const runtime = createLive2D({
-  renderer: customRenderer,
-  backends: [customBackend],
+    renderer: customRenderer,
+    backends: [customBackend],
 });
 ```
 
@@ -183,9 +192,33 @@ 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.16",
+  "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.16",
-    "@doki-land/live2d-loader": "0.0.16",
-    "@doki-land/live2d-renderer": "0.0.16"
+    "@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";