@doki-land/live2d-renderer 0.0.14 → 0.0.16

package/README.md

@@ -1,3 +1,160 @@
 # @doki-land/live2d-renderer
 
-live2d.ts package 0.0.14.
+Model execution and browser-native rendering backends for `live2d.ts`.
+
+This package owns both MOC2/MOC3 runtime behavior and the WebGPU, WebGL2, and Canvas2D graphics implementations.
+Applications should normally use these capabilities through `@doki-land/live2d`.
+
+## ✨ Features
+
+- Pure TypeScript MOC2 and MOC3 parsing paths.
+- CPU model programs and deterministic frame evaluation.
+- WebGPU rendering.
+- WebGL2 rendering.
+- Canvas2D compatibility rendering.
+- Texture, blend mode, clipping, and mask-atlas support.
+- Parameter bindings for inspectors and interactive hosts.
+- Renderer initialization fallback.
+- Structural and model-fixture tests.
+
+## 🧭 Package Role
+
+The source tree separates three concerns:
+
+```text
+src/moc/       model formats, deformation, and ModelBackend implementations
+src/cpu/       model program parsing and CPU frame evaluation
+src/backends/  WebGPU, WebGL2, and Canvas2D graphics backends
+```
+
+MOC2 and MOC3 are model formats, not graphics backends. WebGPU, WebGL2, and Canvas2D are graphics backends, not model
+formats.
+
+## 📦 Installation
+
+```bash
+pnpm add @doki-land/live2d-renderer
+```
+
+Install this package directly when building renderer tools, conformance tests, custom facades, or specialized host
+pipelines.
+
+## 🚀 Creating a Renderer
+
+```ts
+import { createRenderer } from "@doki-land/live2d-renderer";
+
+const renderer = createRenderer({
+  prefer: ["webgpu", "webgl2", "canvas2d"],
+});
+
+await renderer.initialize(canvas);
+```
+
+Fallback occurs during initialization. This matters because browser feature detection alone cannot prove that an
+adapter, device, context, or required capability can be created.
+
+## 🖼️ Backend Selection
+
+### WebGPU
+
+Preferred for modern browsers and explicit GPU resource management. A valid `navigator.gpu` object is not sufficient;
+adapter and device creation can still fail.
+
+### WebGL2
+
+Primary GPU fallback with broad browser support. Shader compilation, framebuffer allocation, texture limits, and context
+loss remain device-dependent.
+
+### Canvas2D
+
+Compatibility and diagnostic path using textured triangle approximation. It is useful for fallback rendering and
+CPU-output inspection but is not expected to match GPU throughput for complex models.
+
+## 🧠 Model Runtime
+
+A `ModelBackend` is responsible for:
+
+- determining whether it can handle normalized model settings;
+- creating model state from settings and binary data;
+- updating model time and parameters;
+- producing drawable meshes or CPU frame snapshots;
+- exposing parameter bindings;
+- releasing model-owned state.
+
+Model runtimes must not create their own application frame loop or DOM controls.
+
+## 🎭 Rendering Semantics
+
+The renderer preserves model-defined behavior including:
+
+- drawable render order;
+- opacity and visibility;
+- normal, additive, and multiplicative blending where implemented;
+- mask relationships;
+- inverted masks;
+- texture coordinates;
+- model-space orientation.
+
+Transparent drawables cannot be freely reordered across characters or masks merely to reduce state changes. Visual
+correctness takes precedence over speculative batching.
+
+## 🧭 Coordinate Contract
+
+Model geometry uses a consistent model-space convention before reaching a graphics backend. Each backend is responsible
+for exactly one conversion to its target coordinate system.
+
+Do not fix orientation problems with CSS canvas transforms. CSS transforms also affect pointer mapping and can hide a
+double conversion instead of correcting the model-to-renderer contract.
+
+Orientation changes require a neutral fixture or pixel evidence across the affected backends.
+
+## ⚡ Performance Engineering
+
+Performance work should target measured costs:
+
+- model-program and instance lifetime;
+- per-frame allocations;
+- parameter dirty tracking;
+- affected deformer and drawable evaluation;
+- dynamic vertex upload ranges;
+- mask-pass reuse;
+- texture and pipeline state changes;
+- overdraw and canvas resolution;
+- multi-character scaling.
+
+WebAssembly, TypeScript, WebGPU, and WebGL2 are implementation tools, not benchmark results. Comparisons must use
+equivalent visual output and report CPU, GPU, allocation, upload, and memory metrics.
+
+## 🧪 Testing
+
+```bash
+pnpm --filter @doki-land/live2d-renderer typecheck
+pnpm --filter @doki-land/live2d-renderer test
+```
+
+Renderer changes should add the smallest appropriate evidence:
+
+- CPU golden snapshots for evaluation changes;
+- structural assertions for format decoding;
+- orientation tests for coordinate changes;
+- mask and blend fixtures for compositing changes;
+- pixel comparisons for graphics parity;
+- browser checks for device-specific behavior.
+
+Proprietary models must not be committed without redistribution permission.
+
+## 🔌 Extending the Package
+
+New model-format support belongs under `src/moc/`. New browser graphics implementations belong under `src/backends/`. Do
+not create a separate published package for every MOC revision or GPU backend unless an independently useful public
+contract justifies it.
+
+## 🤝 Contributing
+
+Keep hot paths allocation-aware, preserve deterministic CPU behavior, and document the visual invariant behind renderer
+changes. Generated bundles must be rebuilt from source.
+
+## 📄 License
+
+See the repository license. Model assets used for local testing may have separate terms.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import * as _doki_land_live2d_core from '@doki-land/live2d-core';
 import { ParameterProgram, ModelProgram, ModelInstance, FrameSnapshot, ModelFormat, ModelSettings, AssetResolver, InternalModel } from '@doki-land/live2d-core';
 export { detectModelSettingsFormat } from '@doki-land/live2d-core';
 
@@ -376,6 +377,8 @@ interface ModelBackendOptions {
     resolver?: AssetResolver;
     /** Preloaded moc bytes (tests). */
     mocBytes?: ArrayBuffer;
+    /** Reuse a prior compile from {@link SharedModelCompile}. */
+    sharedCompile?: SharedModelCompile;
 }
 /** Live parameter binding for inspectors / playground. */
 interface ParameterBinding {
@@ -385,6 +388,16 @@ interface ParameterBinding {
     readonly defaultValue: number;
     readonly value: number;
 }
+/** Shared read-only decode payload (renderer-internal; set by stage asset cache). */
+interface SharedModelCompile {
+    readonly mocBytes: ArrayBuffer;
+    /** moc3 official `.moc3` document. */
+    readonly moc3Doc?: unknown;
+    /** moc3 CPU `.program.json` program. */
+    readonly cpuProgram?: _doki_land_live2d_core.ModelProgram;
+    /** Parsed moc2 model graph. */
+    readonly moc2Model?: unknown;
+}
 /** moc2 / moc3 model runtime. */
 interface ModelBackend {
     readonly format: ModelFormat;
@@ -525,6 +538,9 @@ declare const PREVIEW_STROKE: {
 /** Expand triangle indices into a line-list (each edge twice-wound). */
 declare function triangleEdgesToLineList(indices: Uint16Array): Uint16Array;
 
+/** One-time decode of moc bytes for stage-level {@link ModelAsset} sharing. */
+declare function compileSharedModelCompile(settings: ModelSettings, mocBytes: ArrayBuffer): SharedModelCompile;
+
 /**
  * `@doki-land/live2d-renderer`
  *
@@ -537,4 +553,4 @@ declare function triangleEdgesToLineList(indices: Uint16Array): Uint16Array;
 
 declare const LIVE2D_RENDERER_VERSION: "0.0.0";
 
-export { BlendMode, CPU_PROGRAM_KIND, Canvas2DRendererImpl, type Canvas2DRendererOptions, type ClippingContext, type ClippingDrawableRef, type ClippingPartition, type CpuProgramFile, type CreateRendererOptions, type DecodedMoc2, type DecodedMoc3, type DrawableMesh, FULL_NDC_BOUNDS, LIVE2D_RENDERER_VERSION, type LaidOutClippingContext, MASK_CHANNEL_FLAGS, type MaskAtlasMode, type MaskAtlasOptions, type MaskChannelFlag, type MaskLayoutRect, Moc2Backend, Moc3Backend, Moc3DrawableFlag, type Moc3GlueDef, type Moc3GluePair, type ModelBackend, type ModelBackendOptions, type ModelDrawPass, PREVIEW_FILL, PREVIEW_STROKE, type ParameterBinding, type Renderer, type RendererKind, type TextureData, type WebGl2Renderer, WebGl2RendererImpl, type WebGl2RendererOptions, type WebGpuRenderer, WebGpuRendererImpl, type WebGpuRendererOptions, applyMoc3Glues, applyWebGl2BlendMode, buildClippingContexts, calcClippedDrawableBounds, calcVertexBounds, canvasCompositeForBlendMode, createCanvas2DRenderer, createMoc2Backend, createMoc3Backend, createModelInstance, createQuadProgram, createRenderer, createWebGl2Renderer, createWebGpuRenderer, decodeMoc2, decodeMoc2ColorComposition, decodeMoc3, decodeMoc3DrawableFlags, detectMocBinaryFormat, evaluateFrame, expandBounds, fingerprintSnapshot, fitClippingContexts, isCanvas2DAvailable, isCpuProgramBytes, isWebGl2Available, isWebGpuAvailable, layoutMaskAtlas, layoutMaskAtlasRgba, layoutMaskAtlasUvGrid, loadMoc3Glues, maskChannelVec4, maskLayoutVec4, meanGlueSeamDistance, parseCpuProgram, partitionForClipping, selectModelBackend, serializeCpuProgram, setParameterValue, triangleEdgesToLineList, webGpuBlendState };
+export { BlendMode, CPU_PROGRAM_KIND, Canvas2DRendererImpl, type Canvas2DRendererOptions, type ClippingContext, type ClippingDrawableRef, type ClippingPartition, type CpuProgramFile, type CreateRendererOptions, type DecodedMoc2, type DecodedMoc3, type DrawableMesh, FULL_NDC_BOUNDS, LIVE2D_RENDERER_VERSION, type LaidOutClippingContext, MASK_CHANNEL_FLAGS, type MaskAtlasMode, type MaskAtlasOptions, type MaskChannelFlag, type MaskLayoutRect, Moc2Backend, Moc3Backend, Moc3DrawableFlag, type Moc3GlueDef, type Moc3GluePair, type ModelBackend, type ModelBackendOptions, type ModelDrawPass, PREVIEW_FILL, PREVIEW_STROKE, type ParameterBinding, type Renderer, type RendererKind, type SharedModelCompile, type TextureData, type WebGl2Renderer, WebGl2RendererImpl, type WebGl2RendererOptions, type WebGpuRenderer, WebGpuRendererImpl, type WebGpuRendererOptions, applyMoc3Glues, applyWebGl2BlendMode, buildClippingContexts, calcClippedDrawableBounds, calcVertexBounds, canvasCompositeForBlendMode, compileSharedModelCompile, createCanvas2DRenderer, createMoc2Backend, createMoc3Backend, createModelInstance, createQuadProgram, createRenderer, createWebGl2Renderer, createWebGpuRenderer, decodeMoc2, decodeMoc2ColorComposition, decodeMoc3, decodeMoc3DrawableFlags, detectMocBinaryFormat, evaluateFrame, expandBounds, fingerprintSnapshot, fitClippingContexts, isCanvas2DAvailable, isCpuProgramBytes, isWebGl2Available, isWebGpuAvailable, layoutMaskAtlas, layoutMaskAtlasRgba, layoutMaskAtlasUvGrid, loadMoc3Glues, maskChannelVec4, maskLayoutVec4, meanGlueSeamDistance, parseCpuProgram, partitionForClipping, selectModelBackend, serializeCpuProgram, setParameterValue, triangleEdgesToLineList, webGpuBlendState };

package/dist/index.js

@@ -5236,7 +5236,8 @@ var Moc2Backend = class {
     return detectModelSettingsFormat2(json) === "moc2";
   }
   async createModel(settings, options) {
-    let bytes = options?.mocBytes;
+    const shared = options?.sharedCompile;
+    let bytes = options?.mocBytes ?? shared?.mocBytes;
     if (!bytes) {
       if (!options?.resolver) {
         throw new Error(
@@ -5245,7 +5246,7 @@ var Moc2Backend = class {
       }
       bytes = await options.resolver.fetchBytes(settings.moc);
     }
-    const moc = new Moc2Parser(bytes).parseModel();
+    const moc = shared?.moc2Model ?? new Moc2Parser(bytes).parseModel();
     const program = moc2ModelToProgram(moc);
     const instance = createModelInstance(program);
     const model = {
@@ -5400,7 +5401,8 @@ var Moc3Backend = class {
     return detectModelSettingsFormat3(json) === "moc3";
   }
   async createModel(settings, options) {
-    let bytes = options?.mocBytes;
+    const shared = options?.sharedCompile;
+    let bytes = options?.mocBytes ?? shared?.mocBytes;
     if (!bytes) {
       if (!options?.resolver) {
         throw new Error(
@@ -5413,9 +5415,9 @@ var Moc3Backend = class {
     let doc = null;
     let program;
     if (isCpu) {
-      program = parseCpuProgram(bytes);
+      program = shared?.cpuProgram ?? parseCpuProgram(bytes);
     } else {
-      doc = parseMoc3Document(bytes);
+      doc = shared?.moc3Doc ?? parseMoc3Document(bytes);
       program = moc3DocumentToProgram(doc);
     }
     const instance = createModelInstance(program);
@@ -5521,6 +5523,22 @@ function selectModelBackend(backends, json) {
   return hit;
 }
 
+// src/shared-compile.ts
+function compileSharedModelCompile(settings, mocBytes) {
+  if (settings.format === "moc2") {
+    return {
+      mocBytes,
+      moc2Model: new Moc2Parser(mocBytes).parseModel()
+    };
+  }
+  const isCpu = settings.moc.toLowerCase().endsWith(".program.json") || isCpuProgramBytes(mocBytes);
+  if (isCpu) {
+    const cpuProgram = parseCpuProgram(mocBytes);
+    return { mocBytes, cpuProgram };
+  }
+  return { mocBytes, moc3Doc: parseMoc3Document(mocBytes) };
+}
+
 // src/index.ts
 var LIVE2D_RENDERER_VERSION = "0.0.0";
 export {
@@ -5543,6 +5561,7 @@ export {
   calcClippedDrawableBounds,
   calcVertexBounds,
   canvasCompositeForBlendMode,
+  compileSharedModelCompile,
   createCanvas2DRenderer,
   createMoc2Backend,
   createMoc3Backend,

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@doki-land/live2d-renderer",
-  "version": "0.0.14",
-  "description": "Live2D graphics backends (WebGPU/WebGL2/Canvas2D) plus moc2/moc3 CPU model runtimes",
+  "version": "0.0.16",
+  "description": "Live2D rendering — moc2/moc3 decode + WebGPU, WebGL2, Canvas2D backends for live2d.ts.",
   "type": "module",
   "license": "MIT",
-  "author": "Doki Land",
+  "homepage": "https://github.com/doki-land/live2d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/live2d.ts.git",
+    "directory": "projects/live2d-renderer"
+  },
   "keywords": [
     "live2d",
     "webgpu",
@@ -20,7 +25,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "README.md"
   ],
   "publishConfig": {
     "access": "public",
@@ -39,11 +45,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@doki-land/live2d-core": "0.0.14"
+    "@doki-land/live2d-core": "0.0.16"
   },
-  "sideEffects": false,
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/doki-land/live2d.ts.git"
-  }
+  "sideEffects": false
 }

package/src/index.ts

@@ -100,6 +100,7 @@ export {
     type ModelBackend,
     type ModelBackendOptions,
     type ParameterBinding,
+    type SharedModelCompile,
     selectModelBackend,
 } from "./model-runtime.js";
 export {
@@ -107,6 +108,7 @@ export {
     PREVIEW_STROKE,
     triangleEdgesToLineList,
 } from "./preview-style.js";
+export { compileSharedModelCompile } from "./shared-compile.js";
 export {
     BlendMode,
     type DrawableMesh,

package/src/moc/moc2.ts

@@ -92,7 +92,8 @@ export class Moc2Backend implements ModelBackend {
         settings: ModelSettings,
         options?: ModelBackendOptions,
     ): Promise<InternalModel> {
-        let bytes = options?.mocBytes;
+        const shared = options?.sharedCompile;
+        let bytes = options?.mocBytes ?? shared?.mocBytes;
         if (!bytes) {
             if (!options?.resolver) {
                 throw new Error(
@@ -102,7 +103,9 @@ export class Moc2Backend implements ModelBackend {
             bytes = await options.resolver.fetchBytes(settings.moc);
         }
 
-        const moc = new Moc2Parser(bytes).parseModel();
+        const moc =
+            (shared?.moc2Model as Moc2ModelImpl | undefined) ??
+            new Moc2Parser(bytes).parseModel();
         const program = moc2ModelToProgram(moc);
         const instance = createModelInstance(program);
         const model: InternalModel = {

package/src/moc/moc3.ts

@@ -94,7 +94,8 @@ export class Moc3Backend implements ModelBackend {
         settings: ModelSettings,
         options?: ModelBackendOptions,
     ): Promise<InternalModel> {
-        let bytes = options?.mocBytes;
+        const shared = options?.sharedCompile;
+        let bytes = options?.mocBytes ?? shared?.mocBytes;
         if (!bytes) {
             if (!options?.resolver) {
                 throw new Error(
@@ -111,9 +112,11 @@ export class Moc3Backend implements ModelBackend {
         let doc: Moc3Document | null = null;
         let program: ModelProgram;
         if (isCpu) {
-            program = parseCpuProgram(bytes);
+            program = shared?.cpuProgram ?? parseCpuProgram(bytes);
         } else {
-            doc = parseMoc3Document(bytes);
+            doc =
+                (shared?.moc3Doc as Moc3Document | undefined) ??
+                parseMoc3Document(bytes);
             program = moc3DocumentToProgram(doc);
         }
 

package/src/model-runtime.ts

@@ -18,6 +18,8 @@ export interface ModelBackendOptions {
     resolver?: AssetResolver;
     /** Preloaded moc bytes (tests). */
     mocBytes?: ArrayBuffer;
+    /** Reuse a prior compile from {@link SharedModelCompile}. */
+    sharedCompile?: SharedModelCompile;
 }
 
 /** Live parameter binding for inspectors / playground. */
@@ -29,6 +31,17 @@ export interface ParameterBinding {
     readonly value: number;
 }
 
+/** Shared read-only decode payload (renderer-internal; set by stage asset cache). */
+export interface SharedModelCompile {
+    readonly mocBytes: ArrayBuffer;
+    /** moc3 official `.moc3` document. */
+    readonly moc3Doc?: unknown;
+    /** moc3 CPU `.program.json` program. */
+    readonly cpuProgram?: import("@doki-land/live2d-core").ModelProgram;
+    /** Parsed moc2 model graph. */
+    readonly moc2Model?: unknown;
+}
+
 /** moc2 / moc3 model runtime. */
 export interface ModelBackend {
     readonly format: ModelFormat;

package/src/shared-compile.ts

@@ -0,0 +1,28 @@
+import type { ModelProgram, ModelSettings } from "@doki-land/live2d-core";
+import { isCpuProgramBytes, parseCpuProgram } from "./cpu/cpu-program.js";
+import { Moc2Parser } from "./moc/moc2-objects.js";
+import { parseMoc3Document } from "./moc/moc3-reader.js";
+import type { SharedModelCompile } from "./model-runtime.js";
+
+/** One-time decode of moc bytes for stage-level {@link ModelAsset} sharing. */
+export function compileSharedModelCompile(
+    settings: ModelSettings,
+    mocBytes: ArrayBuffer,
+): SharedModelCompile {
+    if (settings.format === "moc2") {
+        return {
+            mocBytes,
+            moc2Model: new Moc2Parser(mocBytes).parseModel(),
+        };
+    }
+
+    const isCpu =
+        settings.moc.toLowerCase().endsWith(".program.json") ||
+        isCpuProgramBytes(mocBytes);
+    if (isCpu) {
+        const cpuProgram: ModelProgram = parseCpuProgram(mocBytes);
+        return { mocBytes, cpuProgram };
+    }
+
+    return { mocBytes, moc3Doc: parseMoc3Document(mocBytes) };
+}