@doki-land/live2d-renderer 0.0.16 → 0.0.17

package/README.md

@@ -19,12 +19,15 @@ Applications should normally use these capabilities through `@doki-land/live2d`.
 
 ## 🧭 Package Role
 
-The source tree separates three concerns:
+The source tree separates execution 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
+src/moc/       MOC2/MOC3 decode, deformation, and ModelBackend implementations
+src/cpu/       model program parsing and CPU frame evaluation
+src/render/    blend modes, clipping, coords, preview styling
+src/runtime/   renderer factory and model-runtime glue
+src/format/    moc binary and settings format peek helpers
 ```
 
 MOC2 and MOC3 are model formats, not graphics backends. WebGPU, WebGL2, and Canvas2D are graphics backends, not model
@@ -42,10 +45,10 @@ pipelines.
 ## 🚀 Creating a Renderer
 
 ```ts
-import { createRenderer } from "@doki-land/live2d-renderer";
+import {createRenderer} from "@doki-land/live2d-renderer";
 
 const renderer = createRenderer({
-  prefer: ["webgpu", "webgl2", "canvas2d"],
+    prefer: ["webgpu", "webgl2", "canvas2d"],
 });
 
 await renderer.initialize(canvas);
@@ -152,9 +155,34 @@ 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.
+### Renderer expectations
+
+- Keep hot paths allocation-aware.
+- Preserve deterministic CPU behavior.
+- Document the visual invariant behind renderer changes.
+- Add structural, pixel, or browser evidence appropriate to the change.
+- Rebuild generated bundles from source instead of editing them manually.
 
 ## 📄 License
 
-See the repository license. Model assets used for local testing may have separate terms.
+### Clean-room rendering
+
+- WGSL and GLSL shaders, graphics pipelines, mask and blend paths, model execution, Canvas2D mesh rendering, resource
+  lifecycle, and GPU submission optimizations are independently designed and handwritten.
+- No implementation is copied, translated, ported, derived from, or linked against an official renderer, Core binary,
+  SDK wrapper, shader source, pipeline implementation, or internal API.
+- External format names identify interoperability targets only.
+- The maintainers and contributors are independent and are not employed by, affiliated with, sponsored by, endorsed by,
+  or acting on behalf of the official Cubism SDK vendor.
+
+### Contribution boundary
+
+- Do not submit official SDK or shader source, disassembly-derived implementations, mechanically translated code, or
+  dependencies on an official runtime.
+- Support compatibility patches with a public format fact, neutral fixture, reproducible independent observation, or
+  independently authored technical rationale.
+
+### Terms
+
+- See the repository license for source-code terms.
+- Model assets used for local testing may have separate terms.

package/dist/index.d.ts

@@ -335,10 +335,10 @@ interface DecodedMoc3 {
     readonly format: "moc3";
     readonly program: ModelProgram;
 }
-/** Decode official moc2 (`.moc`) bytes into a default-pose ModelProgram. */
+/** Decode binary moc2 (`.moc`) bytes into a default-pose ModelProgram. */
 declare function decodeMoc2(bytes: ArrayBuffer): Promise<DecodedMoc2>;
 /**
- * Decode official moc3 bytes into a ModelProgram.
+ * Decode binary moc3 bytes into a ModelProgram.
  * Applies keyform blending + warp/rotation deformer chains at the given pose
  * (defaults when called via decodeMoc3).
  */
@@ -347,7 +347,7 @@ declare function decodeMoc3(bytes: ArrayBuffer): Promise<DecodedMoc3>;
 /**
  * Shared moc2/moc3 drawable constant-flag decode → blend / invert-mask.
  */
-/** Cubism Core constant drawable flag bits (moc3 art_mesh.drawable_flags). */
+/** Drawable flag bits decoded from the supported MOC3 art-mesh records. */
 declare const Moc3DrawableFlag: {
     readonly BlendAdditive: number;
     readonly BlendMultiplicative: number;
@@ -391,7 +391,7 @@ interface ParameterBinding {
 /** Shared read-only decode payload (renderer-internal; set by stage asset cache). */
 interface SharedModelCompile {
     readonly mocBytes: ArrayBuffer;
-    /** moc3 official `.moc3` document. */
+    /** Parsed binary `.moc3` document. */
     readonly moc3Doc?: unknown;
     /** moc3 CPU `.program.json` program. */
     readonly cpuProgram?: _doki_land_live2d_core.ModelProgram;
@@ -431,7 +431,7 @@ declare class Moc2Backend implements ModelBackend {
 }
 declare function createMoc2Backend(): Moc2Backend;
 
-/** moc3 model backend — official `.moc3` or CPU `.program.json` fixture. */
+/** moc3 model backend for binary `.moc3` input or CPU `.program.json` fixtures. */
 declare class Moc3Backend implements ModelBackend {
     readonly format: "moc3";
     canHandle(json: unknown): boolean;
@@ -468,7 +468,7 @@ interface Moc3KeyTables {
 }
 
 /**
- * Parse official MOC3 bytes into typed section tables (no deform evaluation).
+ * Parse binary MOC3 input into typed section tables (no deform evaluation).
  */
 interface Moc3CanvasInfo {
     readonly pixelsPerUnit: number;
@@ -548,6 +548,9 @@ declare function compileSharedModelCompile(settings: ModelSettings, mocBytes: Ar
  * - `backends/`  — graphics only (webgpu / webgl2 / canvas2d)
  * - `moc/`       — moc2 / moc3 decode + model runtimes (not graphics backends)
  * - `cpu/`       — CPU evaluate + cpu-program fixture codec
+ * - `render/`    — blend, clipping, coords, preview styling helpers
+ * - `runtime/`   — renderer factory + model runtime glue
+ * - `format/`    — moc binary / settings format peek (shared with core)
  * - `tests/`     — all vitest suites (package root)
  */
 

package/dist/index.js

@@ -5,7 +5,7 @@ var BlendMode = {
   Multiplicative: 2
 };
 
-// src/blend.ts
+// src/render/blend.ts
 function applyWebGl2BlendMode(gl, mode) {
   gl.enable(gl.BLEND);
   switch (mode) {
@@ -84,7 +84,7 @@ function webGpuBlendState(mode) {
   }
 }
 
-// src/clipping.ts
+// src/render/clipping.ts
 var MASK_CHANNEL_FLAGS = [
   [1, 0, 0, 0],
   [0, 1, 0, 0],
@@ -329,7 +329,7 @@ function maskChannelVec4(flag) {
   return new Float32Array([flag[0], flag[1], flag[2], flag[3]]);
 }
 
-// src/coords.ts
+// src/render/coords.ts
 function modelYUpToCanvasPixelY(modelY, canvasHeight) {
   return (1 - modelY) * (canvasHeight / 2);
 }
@@ -337,7 +337,7 @@ function modelXToCanvasPixelX(modelX, canvasWidth) {
   return (modelX + 1) * (canvasWidth / 2);
 }
 
-// src/preview-style.ts
+// src/render/preview-style.ts
 var PREVIEW_FILL = {
   r: 91 / 255,
   g: 141 / 255,
@@ -2620,7 +2620,7 @@ function fingerprintSnapshot(snapshot) {
   return parts.join("|");
 }
 
-// src/create-renderer.ts
+// src/runtime/create-renderer.ts
 var DEFAULT_PREFER = ["webgpu", "webgl2", "canvas2d"];
 var INIT_TIMEOUT_MS = {
   webgpu: 2500,
@@ -2711,7 +2711,7 @@ function createRenderer(options = {}) {
   return new FallbackRenderer(prefer, options);
 }
 
-// src/detect-format.ts
+// src/format/detect-format.ts
 import { detectModelSettingsFormat } from "@doki-land/live2d-core";
 function detectMocBinaryFormat(bytes) {
   if (bytes.byteLength < 4) return null;
@@ -5512,7 +5512,7 @@ function createMoc3Backend() {
   return new Moc3Backend();
 }
 
-// src/model-runtime.ts
+// src/runtime/model-runtime.ts
 function selectModelBackend(backends, json) {
   const hit = backends.find((b) => b.canHandle(json));
   if (!hit) {
@@ -5523,7 +5523,7 @@ function selectModelBackend(backends, json) {
   return hit;
 }
 
-// src/shared-compile.ts
+// src/runtime/shared-compile.ts
 function compileSharedModelCompile(settings, mocBytes) {
   if (settings.format === "moc2") {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doki-land/live2d-renderer",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "Live2D rendering — moc2/moc3 decode + WebGPU, WebGL2, Canvas2D backends for live2d.ts.",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@doki-land/live2d-core": "0.0.16"
+    "@doki-land/live2d-core": "0.0.17"
   },
   "sideEffects": false
 }

package/src/backends/canvas2d.ts

@@ -1,11 +1,14 @@
-import { canvasCompositeForBlendMode } from "../blend.js";
+import { canvasCompositeForBlendMode } from "../render/blend.js";
 import {
     fitClippingContexts,
     type MaskLayoutRect,
     partitionForClipping,
-} from "../clipping.js";
-import { modelXToCanvasPixelX, modelYUpToCanvasPixelY } from "../coords.js";
-import { PREVIEW_FILL, PREVIEW_STROKE } from "../preview-style.js";
+} from "../render/clipping.js";
+import {
+    modelXToCanvasPixelX,
+    modelYUpToCanvasPixelY,
+} from "../render/coords.js";
+import { PREVIEW_FILL, PREVIEW_STROKE } from "../render/preview-style.js";
 import type {
     DrawableMesh,
     ModelDrawPass,

package/src/backends/webgl2.ts

@@ -5,7 +5,7 @@
  * multiply drawable alpha by the mask (or 1−mask when inverted).
  */
 
-import { applyWebGl2BlendMode } from "../blend.js";
+import { applyWebGl2BlendMode } from "../render/blend.js";
 import {
     fitClippingContexts,
     type LaidOutClippingContext,
@@ -13,12 +13,12 @@ import {
     maskChannelVec4,
     maskLayoutVec4,
     partitionForClipping,
-} from "../clipping.js";
+} from "../render/clipping.js";
 import {
     PREVIEW_FILL,
     PREVIEW_STROKE,
     triangleEdgesToLineList,
-} from "../preview-style.js";
+} from "../render/preview-style.js";
 import type {
     DrawableMesh,
     ModelDrawPass,

package/src/backends/webgpu.ts

@@ -6,7 +6,7 @@
  * atlas layout; endFrame submits.
  */
 
-import { webGpuBlendState } from "../blend.js";
+import { webGpuBlendState } from "../render/blend.js";
 import {
     fitClippingContexts,
     type LaidOutClippingContext,
@@ -14,12 +14,12 @@ import {
     maskChannelVec4,
     maskLayoutVec4,
     partitionForClipping,
-} from "../clipping.js";
+} from "../render/clipping.js";
 import {
     PREVIEW_FILL,
     PREVIEW_STROKE,
     triangleEdgesToLineList,
-} from "../preview-style.js";
+} from "../render/preview-style.js";
 import type {
     DrawableMesh,
     ModelDrawPass,

package/src/index.ts

@@ -5,6 +5,9 @@
  * - `backends/`  — graphics only (webgpu / webgl2 / canvas2d)
  * - `moc/`       — moc2 / moc3 decode + model runtimes (not graphics backends)
  * - `cpu/`       — CPU evaluate + cpu-program fixture codec
+ * - `render/`    — blend, clipping, coords, preview styling helpers
+ * - `runtime/`   — renderer factory + model runtime glue
+ * - `format/`    — moc binary / settings format peek (shared with core)
  * - `tests/`     — all vitest suites (package root)
  */
 
@@ -30,7 +33,7 @@ export {
     applyWebGl2BlendMode,
     canvasCompositeForBlendMode,
     webGpuBlendState,
-} from "./blend.js";
+} from "./render/blend.js";
 export {
     buildClippingContexts,
     type ClippingContext,
@@ -53,7 +56,7 @@ export {
     maskChannelVec4,
     maskLayoutVec4,
     partitionForClipping,
-} from "./clipping.js";
+} from "./render/clipping.js";
 export {
     CPU_PROGRAM_KIND,
     type CpuProgramFile,
@@ -71,11 +74,11 @@ export {
 export {
     type CreateRendererOptions,
     createRenderer,
-} from "./create-renderer.js";
+} from "./runtime/create-renderer.js";
 export {
     detectMocBinaryFormat,
     detectModelSettingsFormat,
-} from "./detect-format.js";
+} from "./format/detect-format.js";
 export {
     type DecodedMoc2,
     type DecodedMoc3,
@@ -102,13 +105,13 @@ export {
     type ParameterBinding,
     type SharedModelCompile,
     selectModelBackend,
-} from "./model-runtime.js";
+} from "./runtime/model-runtime.js";
 export {
     PREVIEW_FILL,
     PREVIEW_STROKE,
     triangleEdgesToLineList,
-} from "./preview-style.js";
-export { compileSharedModelCompile } from "./shared-compile.js";
+} from "./render/preview-style.js";
+export { compileSharedModelCompile } from "./runtime/shared-compile.js";
 export {
     BlendMode,
     type DrawableMesh,

package/src/moc/decode.ts

@@ -23,7 +23,7 @@ function readMagic(bytes: ArrayBuffer): string {
     return String.fromCharCode(...new Uint8Array(bytes, 0, 4));
 }
 
-/** Decode official moc2 (`.moc`) bytes into a default-pose ModelProgram. */
+/** Decode binary moc2 (`.moc`) bytes into a default-pose ModelProgram. */
 export async function decodeMoc2(bytes: ArrayBuffer): Promise<DecodedMoc2> {
     if (bytes.byteLength < 4) {
         throw new Error("@doki-land/live2d-renderer: truncated moc2 header");
@@ -48,7 +48,7 @@ export async function decodeMoc2(bytes: ArrayBuffer): Promise<DecodedMoc2> {
 }
 
 /**
- * Decode official moc3 bytes into a ModelProgram.
+ * Decode binary moc3 bytes into a ModelProgram.
  * Applies keyform blending + warp/rotation deformer chains at the given pose
  * (defaults when called via decodeMoc3).
  */

package/src/moc/drawable-flags.ts

@@ -4,7 +4,7 @@
 
 import { FrameBlendMode } from "@doki-land/live2d-core";
 
-/** Cubism Core constant drawable flag bits (moc3 art_mesh.drawable_flags). */
+/** Drawable flag bits decoded from the supported MOC3 art-mesh records. */
 export const Moc3DrawableFlag = {
     BlendAdditive: 1 << 0,
     BlendMultiplicative: 1 << 1,

package/src/moc/moc2-deform.ts

@@ -1,6 +1,6 @@
 /**
  * moc2 default-pose deformer bake: affine + mesh-warp parent chain.
- * Clean-room from public moc2 layout / observed keyform semantics.
+ * Evaluates the parsed keyform tables into drawable-space positions.
  */
 
 import { interpolateKeyforms, resolveKeyformBlend } from "./moc2-keyforms.js";

package/src/moc/moc2-reader.ts

@@ -1,6 +1,6 @@
 /**
  * moc2 binary stream reader (7-bit varints, big-endian ints/floats).
- * Clean-room layout from observed `.moc` bytes + public format notes — no Core code.
+ * Covers the record layout exercised by the repository's supported fixtures.
  */
 
 export const MOC2_REF_TYPE = 33;

package/src/moc/moc2.ts

@@ -15,7 +15,7 @@ import type {
     ModelBackend,
     ModelBackendOptions,
     ParameterBinding,
-} from "../model-runtime.js";
+} from "../runtime/model-runtime.js";
 import type { BlendMode, DrawableMesh } from "../types.js";
 import { type Moc2ModelImpl, Moc2Parser } from "./moc2-objects.js";
 import {

package/src/moc/moc3-deform.ts

@@ -1,7 +1,7 @@
 /**
  * moc3 deformer bake: warp grids + rotation affines along parent chains.
  *
- * Coordinate contract (observed on official MOC3 / Wanko):
+ * Coordinate contract covered by the Wanko regression fixture:
  * - Root rotations author scale ≈ 1/pixelsPerUnit; children stay in pixels.
  * - Nested rotation under rotation: mulAffine; origins/children share parent units.
  * - Rotation under warp: origin is warp UV; fold 1/ppu into the local linear

package/src/moc/moc3-layout.ts

@@ -1,10 +1,7 @@
 /**
- * Official MOC3 section layout (clean-room).
- *
- * Header (64) + Section Offset Table (160 × u32) + body arrays.
- * Layout order follows public MOC3 memory-map descriptions (OpenL2D hexpat /
- * independent format notes). Deformer evaluation is deferred — default pose
- * uses each art mesh's first keyform only.
+ * MOC3 section layout used by the decoder: a 64-byte header, a section-offset
+ * table of 160 u32 entries, and the referenced body arrays. Deformer evaluation
+ * is deferred; the initial pose uses each art mesh's first keyform.
  */
 
 export const MOC3_MAGIC = "MOC3";

package/src/moc/moc3-reader.ts

@@ -1,5 +1,5 @@
 /**
- * Parse official MOC3 bytes into typed section tables (no deform evaluation).
+ * Parse binary MOC3 input into typed section tables (no deform evaluation).
  */
 
 import {

package/src/moc/moc3-to-program.ts

@@ -38,11 +38,9 @@ function normalizePositions(
     canvasHeight: number,
     pixelsPerUnit: number,
 ): Float32Array {
-    // Cubism deformer output is in logical units (canvas / ppu), center origin.
-    // Authoring Y grows upward in the editor, but the runtime draw path that
-    // matches Cubism Web samples presents with Y flipped into our shared
-    // Y-up NDC (head / bowl toward +Y). Negate Y once here — same contract as
-    // moc2 after top-left pixel normalization.
+    // Deformer output uses logical canvas/ppu units around the model center.
+    // Convert the decoded authoring orientation once into the renderer's shared
+    // Y-up NDC contract, matching the moc2 path after top-left normalization.
     const ppu = pixelsPerUnit > 0 ? pixelsPerUnit : 1;
     const hw = canvasWidth > 0 ? (canvasWidth / ppu) * 0.5 : 0.5;
     const hh = canvasHeight > 0 ? (canvasHeight / ppu) * 0.5 : 0.5;

package/src/moc/moc3.ts

@@ -17,7 +17,7 @@ import type {
     ModelBackend,
     ModelBackendOptions,
     ParameterBinding,
-} from "../model-runtime.js";
+} from "../runtime/model-runtime.js";
 import type { BlendMode, DrawableMesh } from "../types.js";
 import { cascadedPartOpacity, readMoc3PartTables } from "./moc3-parts.js";
 import { type Moc3Document, parseMoc3Document } from "./moc3-reader.js";
@@ -49,7 +49,7 @@ function paramFingerprint(values: ArrayLike<number>): string {
 }
 
 interface Moc3State {
-    /** Present for official MOC3; null for cpu-program fixtures. */
+    /** Present for binary MOC3 input; null for cpu-program fixtures. */
     doc: Moc3Document | null;
     instance: ModelInstance;
     lastFrame: FrameSnapshot | null;
@@ -82,7 +82,7 @@ function bakePose(state: Moc3State): void {
     state.lastFrame = evaluateFrame(next);
 }
 
-/** moc3 model backend — official `.moc3` or CPU `.program.json` fixture. */
+/** moc3 model backend for binary `.moc3` input or CPU `.program.json` fixtures. */
 export class Moc3Backend implements ModelBackend {
     readonly format = "moc3" as const;
 

package/src/{blend.ts → render/blend.ts}

@@ -2,7 +2,7 @@
  * Map Live2D blend modes to WebGL / Canvas compositing.
  */
 
-import { BlendMode } from "./types.js";
+import { BlendMode } from "../types.js";
 
 /** Apply premultiplied-friendly Live2D blend factors on a WebGL2 context. */
 export function applyWebGl2BlendMode(

package/src/{create-renderer.ts → runtime/create-renderer.ts}

@@ -1,16 +1,16 @@
 import {
     type Canvas2DRendererOptions,
     createCanvas2DRenderer,
-} from "./backends/canvas2d.js";
+} from "../backends/canvas2d.js";
 import {
     createWebGl2Renderer,
     type WebGl2RendererOptions,
-} from "./backends/webgl2.js";
+} from "../backends/webgl2.js";
 import {
     createWebGpuRenderer,
     type WebGpuRendererOptions,
-} from "./backends/webgpu.js";
-import type { Renderer, RendererKind } from "./types.js";
+} from "../backends/webgpu.js";
+import type { Renderer, RendererKind } from "../types.js";
 
 export interface CreateRendererOptions {
     /**

package/src/{model-runtime.ts → runtime/model-runtime.ts}

@@ -5,7 +5,7 @@ import type {
     ModelFormat,
     ModelSettings,
 } from "@doki-land/live2d-core";
-import type { DrawableMesh, Renderer } from "./types.js";
+import type { DrawableMesh, Renderer } from "../types.js";
 
 /**
  * Model-format runtime contract (moc2 / moc3 / cpu-program).
@@ -34,7 +34,7 @@ export interface ParameterBinding {
 /** Shared read-only decode payload (renderer-internal; set by stage asset cache). */
 export interface SharedModelCompile {
     readonly mocBytes: ArrayBuffer;
-    /** moc3 official `.moc3` document. */
+    /** Parsed binary `.moc3` document. */
     readonly moc3Doc?: unknown;
     /** moc3 CPU `.program.json` program. */
     readonly cpuProgram?: import("@doki-land/live2d-core").ModelProgram;

package/src/{shared-compile.ts → runtime/shared-compile.ts}

@@ -1,7 +1,7 @@
 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 { 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. */