@doki-land/live2d-renderer 0.0.16 → 0.0.18

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

@@ -138,123 +138,6 @@ declare class WebGpuRendererImpl implements WebGpuRenderer {
 declare function createWebGpuRenderer(options?: WebGpuRendererOptions): WebGpuRenderer;
 declare function isWebGpuAvailable(): boolean;
 
-/**
- * Map Live2D blend modes to WebGL / Canvas compositing.
- */
-
-/** Apply premultiplied-friendly Live2D blend factors on a WebGL2 context. */
-declare function applyWebGl2BlendMode(gl: WebGL2RenderingContext, mode: BlendMode): void;
-/** Canvas2D globalCompositeOperation for Live2D blend modes. */
-declare function canvasCompositeForBlendMode(mode: BlendMode): GlobalCompositeOperation;
-/** WebGPU blend state for Live2D modes (straight alpha draw path). */
-declare function webGpuBlendState(mode: BlendMode): GPUBlendState;
-
-/**
- * Clipping-mask context grouping + mask atlas layout.
- *
- * Two packing modes:
- * - `uv-grid`: √N UV cells, alpha channel only (Canvas2D / simple path)
- * - `rgba`: Cubism-style channel × UV packing (≤4 → full UV on R/G/B/A)
- */
-interface ClippingDrawableRef {
-    readonly index: number;
-    readonly maskIndices: readonly number[];
-    readonly invertedMask: boolean;
-}
-interface ClippingContext {
-    /** Stable key: invert flag + sorted mask drawable indices. */
-    readonly key: string;
-    readonly maskIndices: readonly number[];
-    readonly clippedIndices: readonly number[];
-    readonly invertedMask: boolean;
-}
-/** UV-space rectangle inside the shared mask atlas (0..1). */
-interface MaskLayoutRect {
-    readonly x: number;
-    readonly y: number;
-    readonly width: number;
-    readonly height: number;
-}
-/** R/G/B/A write/sample selector (Cubism channelFlag). */
-type MaskChannelFlag = readonly [number, number, number, number];
-declare const MASK_CHANNEL_FLAGS: readonly MaskChannelFlag[];
-type MaskAtlasMode = "uv-grid" | "rgba";
-interface MaskAtlasOptions {
-    /** Packing strategy. Default `rgba` (Cubism density). */
-    readonly mode?: MaskAtlasMode;
-    /** Cell inset for `uv-grid` only (reduces neighbour bleed). */
-    readonly inset?: number;
-    /** Render-texture count for `rgba` (default 1 → max 36). */
-    readonly renderTextureCount?: number;
-}
-interface LaidOutClippingContext extends ClippingContext {
-    readonly layout: MaskLayoutRect;
-    /** 0=R … 3=A. `uv-grid` always uses A (3). */
-    readonly channelIndex: number;
-    readonly channelFlag: MaskChannelFlag;
-    /** Cubism multi-RT buffer index; currently always 0. */
-    readonly bufferIndex: number;
-    /**
-     * Expanded AABB of clipped drawables in vertex/NDC space.
-     * Mask write/sample map this rect into `layout` (Cubism bounds-fit).
-     * Default before `fitClippingContexts`: full NDC (-1..1)².
-     */
-    readonly modelBounds: MaskLayoutRect;
-}
-/** Full clip-space quad used when no valid clipped bounds exist. */
-declare const FULL_NDC_BOUNDS: MaskLayoutRect;
-interface ClippingPartition {
-    readonly contexts: readonly LaidOutClippingContext[];
-    /** Drawables that consume a mask (drawn after mask pass). */
-    readonly clipped: ReadonlySet<number>;
-    /** Drawables used as masks (mask buffer only, not color target). */
-    readonly maskOnly: ReadonlySet<number>;
-}
-/**
- * Group drawables that consume clipping masks into shared contexts.
- * Drawables with empty maskIndices are omitted.
- */
-declare function buildClippingContexts(drawables: readonly ClippingDrawableRef[]): ClippingContext[];
-/**
- * Pack clipping contexts into a square-ish UV grid on one atlas (alpha only).
- */
-declare function layoutMaskAtlasUvGrid(contexts: readonly ClippingContext[], options?: {
-    inset?: number;
-}): LaidOutClippingContext[];
-/**
- * Cubism `setupLayoutBounds`: pack across R/G/B/A then UV cells.
- * Single RT → max 36 (4×9); multi-RT → 32 per sheet.
- */
-declare function layoutMaskAtlasRgba(contexts: readonly ClippingContext[], options?: {
-    renderTextureCount?: number;
-}): LaidOutClippingContext[];
-/** Pack clipping contexts (default: Cubism RGBA density). */
-declare function layoutMaskAtlas(contexts: readonly ClippingContext[], options?: MaskAtlasOptions): LaidOutClippingContext[];
-/** Partition drawables and assign atlas layouts. */
-declare function partitionForClipping(drawables: readonly ClippingDrawableRef[], options?: MaskAtlasOptions): ClippingPartition;
-/** Axis-aligned bounds of interleaved xy vertex positions. */
-declare function calcVertexBounds(positions: Float32Array): MaskLayoutRect | null;
-/** Expand bounds by a relative margin on each axis (Cubism uses 0.05). */
-declare function expandBounds(bounds: MaskLayoutRect, margin?: number): MaskLayoutRect;
-interface MaskBoundsMeshRef {
-    readonly index: number;
-    readonly vertexPositions: Float32Array;
-}
-/**
- * Union AABB of clipped drawables, expanded by margin (Cubism
- * `calcClippedDrawableTotalBounds` + 0.05 expand).
- */
-declare function calcClippedDrawableBounds(clippedIndices: readonly number[], byIndex: ReadonlyMap<number, MaskBoundsMeshRef>, margin?: number): MaskLayoutRect;
-/**
- * Attach per-context `modelBounds` so mask write/sample fit the clipped
- * drawable AABB into the atlas cell (higher mask texel density).
- */
-declare function fitClippingContexts(contexts: readonly LaidOutClippingContext[], byIndex: ReadonlyMap<number, MaskBoundsMeshRef>, margin?: number): LaidOutClippingContext[];
-/** Flatten layout to `[x, y, w, h]` for GPU uniforms. */
-declare function maskLayoutVec4(layout: MaskLayoutRect): Float32Array;
-/** Flatten channel flag to `[r, g, b, a]` for GPU uniforms. */
-declare function maskChannelVec4(flag: MaskChannelFlag): Float32Array;
-
 declare const CPU_PROGRAM_KIND: "cpu-program";
 interface CpuProgramFile {
     readonly kind: typeof CPU_PROGRAM_KIND;
@@ -299,22 +182,6 @@ declare function evaluateFrame(instance: ModelInstance): FrameSnapshot;
 /** Stable fingerprint for golden tests (positions + topology). */
 declare function fingerprintSnapshot(snapshot: FrameSnapshot): string;
 
-interface CreateRendererOptions {
-    /**
-     * Backend try order at initialize time.
-     * Default: `["webgpu", "webgl2", "canvas2d"]`.
-     */
-    prefer?: RendererKind[];
-    webgpu?: WebGpuRendererOptions;
-    webgl2?: WebGl2RendererOptions;
-    canvas2d?: Canvas2DRendererOptions;
-}
-/**
- * Create a renderer provider. Actual backend is chosen on `initialize`
- * (WebGPU → WebGL2 → Canvas2D by default).
- */
-declare function createRenderer(options?: CreateRendererOptions): Renderer;
-
 /**
  * moc binary format peek. Settings JSON detection lives in live2d-core
  * (`detectModelSettingsFormat`) so loader and renderer share one helper.
@@ -335,10 +202,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 +214,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 +258,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 +298,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 +335,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;
@@ -522,6 +389,123 @@ declare function applyMoc3Glues(positionsByMesh: Map<number, Float32Array>, glue
 /** Mean Euclidean distance between glued vertex pairs (for tests). */
 declare function meanGlueSeamDistance(positionsByMesh: ReadonlyMap<number, Float32Array>, glue: Moc3GlueDef): number;
 
+/**
+ * Map Live2D blend modes to WebGL / Canvas compositing.
+ */
+
+/** Apply premultiplied-friendly Live2D blend factors on a WebGL2 context. */
+declare function applyWebGl2BlendMode(gl: WebGL2RenderingContext, mode: BlendMode): void;
+/** Canvas2D globalCompositeOperation for Live2D blend modes. */
+declare function canvasCompositeForBlendMode(mode: BlendMode): GlobalCompositeOperation;
+/** WebGPU blend state for Live2D modes (straight alpha draw path). */
+declare function webGpuBlendState(mode: BlendMode): GPUBlendState;
+
+/**
+ * Clipping-mask context grouping + mask atlas layout.
+ *
+ * Two packing modes:
+ * - `uv-grid`: √N UV cells, alpha channel only (Canvas2D / simple path)
+ * - `rgba`: Cubism-style channel × UV packing (≤4 → full UV on R/G/B/A)
+ */
+interface ClippingDrawableRef {
+    readonly index: number;
+    readonly maskIndices: readonly number[];
+    readonly invertedMask: boolean;
+}
+interface ClippingContext {
+    /** Stable key: invert flag + sorted mask drawable indices. */
+    readonly key: string;
+    readonly maskIndices: readonly number[];
+    readonly clippedIndices: readonly number[];
+    readonly invertedMask: boolean;
+}
+/** UV-space rectangle inside the shared mask atlas (0..1). */
+interface MaskLayoutRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** R/G/B/A write/sample selector (Cubism channelFlag). */
+type MaskChannelFlag = readonly [number, number, number, number];
+declare const MASK_CHANNEL_FLAGS: readonly MaskChannelFlag[];
+type MaskAtlasMode = "uv-grid" | "rgba";
+interface MaskAtlasOptions {
+    /** Packing strategy. Default `rgba` (Cubism density). */
+    readonly mode?: MaskAtlasMode;
+    /** Cell inset for `uv-grid` only (reduces neighbour bleed). */
+    readonly inset?: number;
+    /** Render-texture count for `rgba` (default 1 → max 36). */
+    readonly renderTextureCount?: number;
+}
+interface LaidOutClippingContext extends ClippingContext {
+    readonly layout: MaskLayoutRect;
+    /** 0=R … 3=A. `uv-grid` always uses A (3). */
+    readonly channelIndex: number;
+    readonly channelFlag: MaskChannelFlag;
+    /** Cubism multi-RT buffer index; currently always 0. */
+    readonly bufferIndex: number;
+    /**
+     * Expanded AABB of clipped drawables in vertex/NDC space.
+     * Mask write/sample map this rect into `layout` (Cubism bounds-fit).
+     * Default before `fitClippingContexts`: full NDC (-1..1)².
+     */
+    readonly modelBounds: MaskLayoutRect;
+}
+/** Full clip-space quad used when no valid clipped bounds exist. */
+declare const FULL_NDC_BOUNDS: MaskLayoutRect;
+interface ClippingPartition {
+    readonly contexts: readonly LaidOutClippingContext[];
+    /** Drawables that consume a mask (drawn after mask pass). */
+    readonly clipped: ReadonlySet<number>;
+    /** Drawables used as masks (mask buffer only, not color target). */
+    readonly maskOnly: ReadonlySet<number>;
+}
+/**
+ * Group drawables that consume clipping masks into shared contexts.
+ * Drawables with empty maskIndices are omitted.
+ */
+declare function buildClippingContexts(drawables: readonly ClippingDrawableRef[]): ClippingContext[];
+/**
+ * Pack clipping contexts into a square-ish UV grid on one atlas (alpha only).
+ */
+declare function layoutMaskAtlasUvGrid(contexts: readonly ClippingContext[], options?: {
+    inset?: number;
+}): LaidOutClippingContext[];
+/**
+ * Cubism `setupLayoutBounds`: pack across R/G/B/A then UV cells.
+ * Single RT → max 36 (4×9); multi-RT → 32 per sheet.
+ */
+declare function layoutMaskAtlasRgba(contexts: readonly ClippingContext[], options?: {
+    renderTextureCount?: number;
+}): LaidOutClippingContext[];
+/** Pack clipping contexts (default: Cubism RGBA density). */
+declare function layoutMaskAtlas(contexts: readonly ClippingContext[], options?: MaskAtlasOptions): LaidOutClippingContext[];
+/** Partition drawables and assign atlas layouts. */
+declare function partitionForClipping(drawables: readonly ClippingDrawableRef[], options?: MaskAtlasOptions): ClippingPartition;
+/** Axis-aligned bounds of interleaved xy vertex positions. */
+declare function calcVertexBounds(positions: Float32Array): MaskLayoutRect | null;
+/** Expand bounds by a relative margin on each axis (Cubism uses 0.05). */
+declare function expandBounds(bounds: MaskLayoutRect, margin?: number): MaskLayoutRect;
+interface MaskBoundsMeshRef {
+    readonly index: number;
+    readonly vertexPositions: Float32Array;
+}
+/**
+ * Union AABB of clipped drawables, expanded by margin (Cubism
+ * `calcClippedDrawableTotalBounds` + 0.05 expand).
+ */
+declare function calcClippedDrawableBounds(clippedIndices: readonly number[], byIndex: ReadonlyMap<number, MaskBoundsMeshRef>, margin?: number): MaskLayoutRect;
+/**
+ * Attach per-context `modelBounds` so mask write/sample fit the clipped
+ * drawable AABB into the atlas cell (higher mask texel density).
+ */
+declare function fitClippingContexts(contexts: readonly LaidOutClippingContext[], byIndex: ReadonlyMap<number, MaskBoundsMeshRef>, margin?: number): LaidOutClippingContext[];
+/** Flatten layout to `[x, y, w, h]` for GPU uniforms. */
+declare function maskLayoutVec4(layout: MaskLayoutRect): Float32Array;
+/** Flatten channel flag to `[r, g, b, a]` for GPU uniforms. */
+declare function maskChannelVec4(flag: MaskChannelFlag): Float32Array;
+
 /** Shared untextured preview colors (Canvas2D / WebGL2 / WebGPU parity). */
 declare const PREVIEW_FILL: {
     readonly r: number;
@@ -538,6 +522,22 @@ declare const PREVIEW_STROKE: {
 /** Expand triangle indices into a line-list (each edge twice-wound). */
 declare function triangleEdgesToLineList(indices: Uint16Array): Uint16Array;
 
+interface CreateRendererOptions {
+    /**
+     * Backend try order at initialize time.
+     * Default: `["webgpu", "webgl2", "canvas2d"]`.
+     */
+    prefer?: RendererKind[];
+    webgpu?: WebGpuRendererOptions;
+    webgl2?: WebGl2RendererOptions;
+    canvas2d?: Canvas2DRendererOptions;
+}
+/**
+ * Create a renderer provider. Actual backend is chosen on `initialize`
+ * (WebGPU → WebGL2 → Canvas2D by default).
+ */
+declare function createRenderer(options?: CreateRendererOptions): Renderer;
+
 /** One-time decode of moc bytes for stage-level {@link ModelAsset} sharing. */
 declare function compileSharedModelCompile(settings: ModelSettings, mocBytes: ArrayBuffer): SharedModelCompile;
 
@@ -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,98 +2620,7 @@ function fingerprintSnapshot(snapshot) {
   return parts.join("|");
 }
 
-// src/create-renderer.ts
-var DEFAULT_PREFER = ["webgpu", "webgl2", "canvas2d"];
-var INIT_TIMEOUT_MS = {
-  webgpu: 2500,
-  webgl2: 1500,
-  canvas2d: 1e3
-};
-function instantiate(kind, options) {
-  if (kind === "webgpu") return createWebGpuRenderer(options.webgpu);
-  if (kind === "webgl2") return createWebGl2Renderer(options.webgl2);
-  return createCanvas2DRenderer(options.canvas2d);
-}
-async function initializeWithTimeout(kind, candidate, canvas) {
-  const ms = INIT_TIMEOUT_MS[kind];
-  let timer;
-  try {
-    await Promise.race([
-      candidate.initialize(canvas),
-      new Promise((_, reject) => {
-        timer = setTimeout(() => {
-          reject(
-            new Error(
-              `@doki-land/live2d-renderer: ${kind} initialize timed out after ${ms}ms`
-            )
-          );
-        }, ms);
-      })
-    ]);
-  } finally {
-    if (timer !== void 0) clearTimeout(timer);
-  }
-}
-var FallbackRenderer = class {
-  #inner = null;
-  #kind = "webgpu";
-  #prefer;
-  #options;
-  constructor(prefer, options) {
-    this.#prefer = prefer;
-    this.#options = options;
-  }
-  get kind() {
-    return this.#inner?.kind ?? this.#kind;
-  }
-  async initialize(canvas) {
-    const errors = [];
-    for (const kind of this.#prefer) {
-      const candidate = instantiate(kind, this.#options);
-      try {
-        await initializeWithTimeout(kind, candidate, canvas);
-        this.#inner = candidate;
-        this.#kind = candidate.kind;
-        return;
-      } catch (err) {
-        candidate.destroy();
-        errors.push(
-          `${kind}: ${err instanceof Error ? err.message : String(err)}`
-        );
-      }
-    }
-    throw new Error(
-      `@doki-land/live2d-renderer: no renderer initialized (${errors.join("; ")})`
-    );
-  }
-  createModelDrawPass() {
-    if (!this.#inner) {
-      throw new Error(
-        "@doki-land/live2d-renderer: renderer not initialized"
-      );
-    }
-    return this.#inner.createModelDrawPass();
-  }
-  beginFrame() {
-    this.#inner?.beginFrame();
-  }
-  endFrame() {
-    this.#inner?.endFrame();
-  }
-  resize(width, height) {
-    this.#inner?.resize(width, height);
-  }
-  destroy() {
-    this.#inner?.destroy();
-    this.#inner = null;
-  }
-};
-function createRenderer(options = {}) {
-  const prefer = options.prefer?.length ? options.prefer : DEFAULT_PREFER;
-  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 +5421,98 @@ function createMoc3Backend() {
   return new Moc3Backend();
 }
 
-// src/model-runtime.ts
+// src/runtime/create-renderer.ts
+var DEFAULT_PREFER = ["webgpu", "webgl2", "canvas2d"];
+var INIT_TIMEOUT_MS = {
+  webgpu: 2500,
+  webgl2: 1500,
+  canvas2d: 1e3
+};
+function instantiate(kind, options) {
+  if (kind === "webgpu") return createWebGpuRenderer(options.webgpu);
+  if (kind === "webgl2") return createWebGl2Renderer(options.webgl2);
+  return createCanvas2DRenderer(options.canvas2d);
+}
+async function initializeWithTimeout(kind, candidate, canvas) {
+  const ms = INIT_TIMEOUT_MS[kind];
+  let timer;
+  try {
+    await Promise.race([
+      candidate.initialize(canvas),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(
+            new Error(
+              `@doki-land/live2d-renderer: ${kind} initialize timed out after ${ms}ms`
+            )
+          );
+        }, ms);
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+var FallbackRenderer = class {
+  #inner = null;
+  #kind = "webgpu";
+  #prefer;
+  #options;
+  constructor(prefer, options) {
+    this.#prefer = prefer;
+    this.#options = options;
+  }
+  get kind() {
+    return this.#inner?.kind ?? this.#kind;
+  }
+  async initialize(canvas) {
+    const errors = [];
+    for (const kind of this.#prefer) {
+      const candidate = instantiate(kind, this.#options);
+      try {
+        await initializeWithTimeout(kind, candidate, canvas);
+        this.#inner = candidate;
+        this.#kind = candidate.kind;
+        return;
+      } catch (err) {
+        candidate.destroy();
+        errors.push(
+          `${kind}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    throw new Error(
+      `@doki-land/live2d-renderer: no renderer initialized (${errors.join("; ")})`
+    );
+  }
+  createModelDrawPass() {
+    if (!this.#inner) {
+      throw new Error(
+        "@doki-land/live2d-renderer: renderer not initialized"
+      );
+    }
+    return this.#inner.createModelDrawPass();
+  }
+  beginFrame() {
+    this.#inner?.beginFrame();
+  }
+  endFrame() {
+    this.#inner?.endFrame();
+  }
+  resize(width, height) {
+    this.#inner?.resize(width, height);
+  }
+  destroy() {
+    this.#inner?.destroy();
+    this.#inner = null;
+  }
+};
+function createRenderer(options = {}) {
+  const prefer = options.prefer?.length ? options.prefer : DEFAULT_PREFER;
+  return new FallbackRenderer(prefer, options);
+}
+
+// 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.18",
   "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.18"
   },
   "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)
  */
 
@@ -26,34 +29,6 @@ export {
     WebGpuRendererImpl,
     type WebGpuRendererOptions,
 } from "./backends/webgpu.js";
-export {
-    applyWebGl2BlendMode,
-    canvasCompositeForBlendMode,
-    webGpuBlendState,
-} from "./blend.js";
-export {
-    buildClippingContexts,
-    type ClippingContext,
-    type ClippingDrawableRef,
-    type ClippingPartition,
-    calcClippedDrawableBounds,
-    calcVertexBounds,
-    expandBounds,
-    FULL_NDC_BOUNDS,
-    fitClippingContexts,
-    type LaidOutClippingContext,
-    layoutMaskAtlas,
-    layoutMaskAtlasRgba,
-    layoutMaskAtlasUvGrid,
-    MASK_CHANNEL_FLAGS,
-    type MaskAtlasMode,
-    type MaskAtlasOptions,
-    type MaskChannelFlag,
-    type MaskLayoutRect,
-    maskChannelVec4,
-    maskLayoutVec4,
-    partitionForClipping,
-} from "./clipping.js";
 export {
     CPU_PROGRAM_KIND,
     type CpuProgramFile,
@@ -68,14 +43,10 @@ export {
     fingerprintSnapshot,
     setParameterValue,
 } from "./cpu/evaluate.js";
-export {
-    type CreateRendererOptions,
-    createRenderer,
-} from "./create-renderer.js";
 export {
     detectMocBinaryFormat,
     detectModelSettingsFormat,
-} from "./detect-format.js";
+} from "./format/detect-format.js";
 export {
     type DecodedMoc2,
     type DecodedMoc3,
@@ -96,19 +67,51 @@ export {
     type Moc3GluePair,
     meanGlueSeamDistance,
 } from "./moc/moc3-glue.js";
+export {
+    applyWebGl2BlendMode,
+    canvasCompositeForBlendMode,
+    webGpuBlendState,
+} from "./render/blend.js";
+export {
+    buildClippingContexts,
+    type ClippingContext,
+    type ClippingDrawableRef,
+    type ClippingPartition,
+    calcClippedDrawableBounds,
+    calcVertexBounds,
+    expandBounds,
+    FULL_NDC_BOUNDS,
+    fitClippingContexts,
+    type LaidOutClippingContext,
+    layoutMaskAtlas,
+    layoutMaskAtlasRgba,
+    layoutMaskAtlasUvGrid,
+    MASK_CHANNEL_FLAGS,
+    type MaskAtlasMode,
+    type MaskAtlasOptions,
+    type MaskChannelFlag,
+    type MaskLayoutRect,
+    maskChannelVec4,
+    maskLayoutVec4,
+    partitionForClipping,
+} from "./render/clipping.js";
+export {
+    PREVIEW_FILL,
+    PREVIEW_STROKE,
+    triangleEdgesToLineList,
+} from "./render/preview-style.js";
+export {
+    type CreateRendererOptions,
+    createRenderer,
+} from "./runtime/create-renderer.js";
 export {
     type ModelBackend,
     type ModelBackendOptions,
     type ParameterBinding,
     type SharedModelCompile,
     selectModelBackend,
-} from "./model-runtime.js";
-export {
-    PREVIEW_FILL,
-    PREVIEW_STROKE,
-    triangleEdgesToLineList,
-} from "./preview-style.js";
-export { compileSharedModelCompile } from "./shared-compile.js";
+} from "./runtime/model-runtime.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. */