@doki-land/live2d-loader 0.0.0 → 0.0.11

package/README.md

@@ -1,3 +1,3 @@
 # @doki-land/live2d-loader
 
-Placeholder package (0.0.0). Reserved for doki-land/live2d.ts.
+live2d.ts package 0.0.11.

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { ModelFormat, ModelSettings, AssetKey, AssetResolver } from '@doki-land/live2d-core';
+
+/**
+ * Fetch helpers with optional byte-level progress.
+ */
+type FetchProgressHandler = (update: {
+    bytesLoaded: number;
+    bytesTotal: number | null;
+}) => void;
+/**
+ * Fetch bytes with progress. Uses `arrayBuffer()` when streaming is unavailable
+ * or when Content-Length is known (avoids stuck ReadableStream readers in some
+ * embedded Chromium hosts during rapid remounts).
+ */
+declare function fetchArrayBufferWithProgress(url: string, onProgress?: FetchProgressHandler): Promise<ArrayBuffer>;
+declare function fetchJsonWithProgress(url: string, onProgress?: FetchProgressHandler): Promise<unknown>;
+
+/** Resolve a relative asset URL against the model settings URL. */
+declare function resolveAssetUrl(baseUrl: string, relative: string): string;
+interface UrlAssetResolverOptions {
+    onBytesProgress?: (key: AssetKey, update: {
+        bytesLoaded: number;
+        bytesTotal: number | null;
+    }) => void;
+}
+declare function createUrlAssetResolver(baseUrl: string, options?: UrlAssetResolverOptions): AssetResolver;
+interface LoadPipelineContext {
+    source: string;
+    json?: unknown;
+    format?: ModelFormat;
+    settings?: ModelSettings;
+}
+type LoadMiddleware = (ctx: LoadPipelineContext, next: () => Promise<void>) => Promise<void>;
+declare function runLoadPipeline(ctx: LoadPipelineContext, middlewares: LoadMiddleware[]): Promise<LoadPipelineContext>;
+/** Fetch model settings JSON from a URL. */
+declare function fetchModelJson(url: string, onProgress?: (update: {
+    bytesLoaded: number;
+    bytesTotal: number | null;
+}) => void): Promise<unknown>;
+/** Detect moc2 vs moc3 from settings JSON shape (core helper; throws if unknown). */
+declare function detectModelFormat(json: unknown): ModelFormat;
+/** Normalize raw model3.json / model.json into ModelSettings. */
+declare function normalizeModelSettings(json: unknown, url: string): ModelSettings;
+
+/**
+ * Resolve model settings URLs, including `npm:` specifiers via a CDN.
+ */
+declare const DEFAULT_NPM_CDN = "https://cdn.jsdelivr.net/npm";
+interface ResolveModelSourceOptions {
+    /** Default: `https://cdn.jsdelivr.net/npm` */
+    npmCdnBase?: string;
+}
+/**
+ * Parse `name@version/path`, `@scope/name@version/path`, or `name/path`.
+ * When version is omitted, jsDelivr resolves the latest published version.
+ */
+declare function resolveNpmSpecifier(spec: string, cdnBase?: string): string;
+/**
+ * Turn a model source string into a fetchable URL.
+ * - `npm:pkg[@ver]/path` → CDN URL (jsDelivr by default)
+ * - `http(s)://...` / absolute / relative paths pass through
+ */
+declare function resolveModelSourceUrl(source: string, options?: ResolveModelSourceOptions): string;
+
+/**
+ * `@doki-land/live2d-loader` — model JSON fetch and load pipeline.
+ */
+
+declare const LIVE2D_LOADER_VERSION: "0.0.0";
+
+export { DEFAULT_NPM_CDN, type FetchProgressHandler, LIVE2D_LOADER_VERSION, type LoadMiddleware, type LoadPipelineContext, type ResolveModelSourceOptions, type UrlAssetResolverOptions, createUrlAssetResolver, detectModelFormat, fetchArrayBufferWithProgress, fetchJsonWithProgress, fetchModelJson, normalizeModelSettings, resolveAssetUrl, resolveModelSourceUrl, resolveNpmSpecifier, runLoadPipeline };

package/dist/index.js

@@ -0,0 +1,295 @@
+// src/fetch-progress.ts
+function safeProgress(onProgress, update) {
+  if (!onProgress) return;
+  try {
+    onProgress(update);
+  } catch {
+  }
+}
+async function fetchArrayBufferWithProgress(url, onProgress) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(
+      `@doki-land/live2d-loader: failed to fetch bytes (${res.status}): ${url}`
+    );
+  }
+  const totalHeader = res.headers.get("content-length");
+  const bytesTotal = totalHeader ? Number(totalHeader) : null;
+  const preferBuffer = !res.body || !onProgress || bytesTotal !== null && Number.isFinite(bytesTotal) && bytesTotal >= 0;
+  if (preferBuffer) {
+    safeProgress(onProgress, { bytesLoaded: 0, bytesTotal });
+    const buf = await res.arrayBuffer();
+    safeProgress(onProgress, {
+      bytesLoaded: buf.byteLength,
+      bytesTotal: bytesTotal ?? buf.byteLength
+    });
+    return buf;
+  }
+  const reader = res.body.getReader();
+  const chunks = [];
+  let bytesLoaded = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      chunks.push(value);
+      bytesLoaded += value.byteLength;
+      safeProgress(onProgress, { bytesLoaded, bytesTotal });
+    }
+  }
+  const out = new Uint8Array(bytesLoaded);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  safeProgress(onProgress, {
+    bytesLoaded,
+    bytesTotal: bytesTotal ?? bytesLoaded
+  });
+  return out.buffer;
+}
+async function fetchJsonWithProgress(url, onProgress) {
+  const bytes = await fetchArrayBufferWithProgress(url, onProgress);
+  const text = new TextDecoder().decode(bytes);
+  return JSON.parse(text);
+}
+
+// src/pipeline.ts
+import { detectModelSettingsFormat } from "@doki-land/live2d-core";
+function resolveAssetUrl(baseUrl, relative) {
+  if (/^(?:[a-z]+:)?\/\//i.test(relative) || relative.startsWith("data:")) {
+    return relative;
+  }
+  try {
+    return new URL(relative, baseUrl).href;
+  } catch {
+    const slash = baseUrl.lastIndexOf("/");
+    const dir = slash >= 0 ? baseUrl.slice(0, slash + 1) : "";
+    return `${dir}${relative}`;
+  }
+}
+function createUrlAssetResolver(baseUrl, options = {}) {
+  return {
+    baseUrl,
+    resolve(key) {
+      return resolveAssetUrl(baseUrl, key);
+    },
+    async fetchJson(key) {
+      const url = resolveAssetUrl(baseUrl, key);
+      return fetchJsonWithProgress(url, (update) => {
+        options.onBytesProgress?.(key, update);
+      });
+    },
+    async fetchBytes(key) {
+      const url = resolveAssetUrl(baseUrl, key);
+      return fetchArrayBufferWithProgress(url, (update) => {
+        options.onBytesProgress?.(key, update);
+      });
+    }
+  };
+}
+async function runLoadPipeline(ctx, middlewares) {
+  let index = 0;
+  const dispatch = async () => {
+    const mw = middlewares[index++];
+    if (!mw) return;
+    await mw(ctx, dispatch);
+  };
+  await dispatch();
+  return ctx;
+}
+async function fetchModelJson(url, onProgress) {
+  return fetchJsonWithProgress(url, onProgress);
+}
+function detectModelFormat(json) {
+  if (!json || typeof json !== "object") {
+    throw new Error(
+      "@doki-land/live2d-loader: model json must be an object"
+    );
+  }
+  const format = detectModelSettingsFormat(json);
+  if (!format) {
+    throw new Error(
+      "@doki-land/live2d-loader: unrecognized Live2D model json"
+    );
+  }
+  return format;
+}
+function asStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === "string");
+}
+function normalizeModelSettings(json, url) {
+  const format = detectModelFormat(json);
+  const o = json;
+  if (format === "moc3") {
+    const fileRefs = o.FileReferences;
+    const moc = fileRefs.Moc;
+    const textures = asStringArray(fileRefs.Textures);
+    const motionGroups = {};
+    const motions = fileRefs.Motions;
+    if (motions && typeof motions === "object") {
+      for (const [group, list] of Object.entries(
+        motions
+      )) {
+        if (!Array.isArray(list)) continue;
+        motionGroups[group] = list.map((item) => {
+          if (!item || typeof item !== "object") return null;
+          const file = item.File;
+          if (typeof file !== "string") return null;
+          const def = { file };
+          const sound = item.Sound;
+          if (typeof sound === "string") def.sound = sound;
+          const fadeIn = item.FadeInTime;
+          if (typeof fadeIn === "number") def.fadeInTime = fadeIn;
+          const fadeOut = item.FadeOutTime;
+          if (typeof fadeOut === "number")
+            def.fadeOutTime = fadeOut;
+          return def;
+        }).filter((x) => x !== null);
+      }
+    }
+    const expressions = [];
+    const expr = fileRefs.Expressions;
+    if (Array.isArray(expr)) {
+      for (const item of expr) {
+        if (!item || typeof item !== "object") continue;
+        const name = item.Name;
+        const file = item.File;
+        if (typeof name === "string" && typeof file === "string") {
+          expressions.push({ name, file });
+        }
+      }
+    }
+    const hitAreas = [];
+    if (Array.isArray(o.HitAreas)) {
+      for (const item of o.HitAreas) {
+        if (!item || typeof item !== "object") continue;
+        const name = item.Name;
+        const id = item.Id;
+        if (typeof name === "string" && typeof id === "string") {
+          hitAreas.push({ name, id });
+        }
+      }
+    }
+    return {
+      format: "moc3",
+      url,
+      name: typeof o.Name === "string" ? o.Name : void 0,
+      moc,
+      textures,
+      motionGroups,
+      expressions,
+      physics: typeof fileRefs.Physics === "string" ? fileRefs.Physics : void 0,
+      pose: typeof fileRefs.Pose === "string" ? fileRefs.Pose : void 0,
+      hitAreas
+    };
+  }
+  return {
+    format: "moc2",
+    url,
+    moc: o.model,
+    textures: asStringArray(o.textures),
+    motionGroups: {},
+    expressions: [],
+    hitAreas: []
+  };
+}
+
+// src/resolve-source.ts
+var DEFAULT_NPM_CDN = "https://cdn.jsdelivr.net/npm";
+function resolveNpmSpecifier(spec, cdnBase = DEFAULT_NPM_CDN) {
+  const trimmed = spec.trim().replace(/^\/+/, "");
+  if (!trimmed) {
+    throw new Error("@doki-land/live2d-loader: empty npm model specifier");
+  }
+  let pkg = "";
+  let version = null;
+  let assetPath = "";
+  if (trimmed.startsWith("@")) {
+    const scopeSlash = trimmed.indexOf("/");
+    if (scopeSlash < 0) {
+      throw new Error(
+        `@doki-land/live2d-loader: scoped npm specifier needs /name: ${spec}`
+      );
+    }
+    const afterScope = trimmed.slice(scopeSlash + 1);
+    const at = afterScope.indexOf("@");
+    const slash = afterScope.indexOf("/");
+    if (at >= 0 && (slash < 0 || at < slash)) {
+      pkg = `${trimmed.slice(0, scopeSlash + 1)}${afterScope.slice(0, at)}`;
+      const rest = afterScope.slice(at + 1);
+      const pathSlash = rest.indexOf("/");
+      if (pathSlash < 0) {
+        version = rest;
+      } else {
+        version = rest.slice(0, pathSlash);
+        assetPath = rest.slice(pathSlash + 1);
+      }
+    } else if (slash >= 0) {
+      pkg = `${trimmed.slice(0, scopeSlash + 1)}${afterScope.slice(0, slash)}`;
+      assetPath = afterScope.slice(slash + 1);
+    } else {
+      pkg = trimmed;
+    }
+  } else {
+    const at = trimmed.indexOf("@");
+    const slash = trimmed.indexOf("/");
+    if (at >= 0 && (slash < 0 || at < slash)) {
+      pkg = trimmed.slice(0, at);
+      const rest = trimmed.slice(at + 1);
+      const pathSlash = rest.indexOf("/");
+      if (pathSlash < 0) {
+        version = rest;
+      } else {
+        version = rest.slice(0, pathSlash);
+        assetPath = rest.slice(pathSlash + 1);
+      }
+    } else if (slash >= 0) {
+      pkg = trimmed.slice(0, slash);
+      assetPath = trimmed.slice(slash + 1);
+    } else {
+      pkg = trimmed;
+    }
+  }
+  if (!pkg) {
+    throw new Error(
+      `@doki-land/live2d-loader: invalid npm model specifier: ${spec}`
+    );
+  }
+  if (!assetPath) {
+    throw new Error(
+      `@doki-land/live2d-loader: npm model specifier needs an asset path (got "${spec}")`
+    );
+  }
+  const base = cdnBase.replace(/\/+$/, "");
+  const nameWithVersion = version ? `${pkg}@${version}` : pkg;
+  return `${base}/${nameWithVersion}/${assetPath.replace(/^\/+/, "")}`;
+}
+function resolveModelSourceUrl(source, options = {}) {
+  if (source.startsWith("npm:")) {
+    return resolveNpmSpecifier(
+      source.slice("npm:".length),
+      options.npmCdnBase ?? DEFAULT_NPM_CDN
+    );
+  }
+  return source;
+}
+
+// src/index.ts
+var LIVE2D_LOADER_VERSION = "0.0.0";
+export {
+  DEFAULT_NPM_CDN,
+  LIVE2D_LOADER_VERSION,
+  createUrlAssetResolver,
+  detectModelFormat,
+  fetchArrayBufferWithProgress,
+  fetchJsonWithProgress,
+  fetchModelJson,
+  normalizeModelSettings,
+  resolveAssetUrl,
+  resolveModelSourceUrl,
+  resolveNpmSpecifier,
+  runLoadPipeline
+};

package/package.json

@@ -1,7 +1,46 @@
 {
   "name": "@doki-land/live2d-loader",
-  "version": "0.0.0",
-  "description": "live2d.ts placeholder — not for production use.",
+  "version": "0.0.11",
+  "description": "Live2D asset resolve and model load pipeline",
+  "type": "module",
   "license": "MIT",
-  "private": false
+  "author": "Doki Land",
+  "keywords": [
+    "live2d",
+    "loader",
+    "doki-land"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@doki-land/live2d-core": "0.0.11"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/live2d.ts.git"
+  }
 }

package/src/fetch-progress.ts

@@ -0,0 +1,89 @@
+/**
+ * Fetch helpers with optional byte-level progress.
+ */
+
+export type FetchProgressHandler = (update: {
+    bytesLoaded: number;
+    bytesTotal: number | null;
+}) => void;
+
+function safeProgress(
+    onProgress: FetchProgressHandler | undefined,
+    update: { bytesLoaded: number; bytesTotal: number | null },
+): void {
+    if (!onProgress) return;
+    try {
+        onProgress(update);
+    } catch {
+        // Progress UI must never abort the fetch.
+    }
+}
+
+/**
+ * Fetch bytes with progress. Uses `arrayBuffer()` when streaming is unavailable
+ * or when Content-Length is known (avoids stuck ReadableStream readers in some
+ * embedded Chromium hosts during rapid remounts).
+ */
+export async function fetchArrayBufferWithProgress(
+    url: string,
+    onProgress?: FetchProgressHandler,
+): Promise<ArrayBuffer> {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(
+            `@doki-land/live2d-loader: failed to fetch bytes (${res.status}): ${url}`,
+        );
+    }
+
+    const totalHeader = res.headers.get("content-length");
+    const bytesTotal = totalHeader ? Number(totalHeader) : null;
+    const preferBuffer =
+        !res.body ||
+        !onProgress ||
+        (bytesTotal !== null && Number.isFinite(bytesTotal) && bytesTotal >= 0);
+
+    if (preferBuffer) {
+        safeProgress(onProgress, { bytesLoaded: 0, bytesTotal });
+        const buf = await res.arrayBuffer();
+        safeProgress(onProgress, {
+            bytesLoaded: buf.byteLength,
+            bytesTotal: bytesTotal ?? buf.byteLength,
+        });
+        return buf;
+    }
+
+    const reader = res.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let bytesLoaded = 0;
+
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) {
+            chunks.push(value);
+            bytesLoaded += value.byteLength;
+            safeProgress(onProgress, { bytesLoaded, bytesTotal });
+        }
+    }
+
+    const out = new Uint8Array(bytesLoaded);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    safeProgress(onProgress, {
+        bytesLoaded,
+        bytesTotal: bytesTotal ?? bytesLoaded,
+    });
+    return out.buffer;
+}
+
+export async function fetchJsonWithProgress(
+    url: string,
+    onProgress?: FetchProgressHandler,
+): Promise<unknown> {
+    const bytes = await fetchArrayBufferWithProgress(url, onProgress);
+    const text = new TextDecoder().decode(bytes);
+    return JSON.parse(text) as unknown;
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * `@doki-land/live2d-loader` — model JSON fetch and load pipeline.
+ */
+
+export {
+    type FetchProgressHandler,
+    fetchArrayBufferWithProgress,
+    fetchJsonWithProgress,
+} from "./fetch-progress.js";
+export {
+    createUrlAssetResolver,
+    detectModelFormat,
+    fetchModelJson,
+    type LoadMiddleware,
+    type LoadPipelineContext,
+    normalizeModelSettings,
+    resolveAssetUrl,
+    runLoadPipeline,
+    type UrlAssetResolverOptions,
+} from "./pipeline.js";
+export {
+    DEFAULT_NPM_CDN,
+    type ResolveModelSourceOptions,
+    resolveModelSourceUrl,
+    resolveNpmSpecifier,
+} from "./resolve-source.js";
+
+export const LIVE2D_LOADER_VERSION = "0.0.0" as const;

package/src/pipeline.ts

@@ -0,0 +1,208 @@
+import type {
+    AssetKey,
+    AssetResolver,
+    ExpressionDefinition,
+    HitAreaDefinition,
+    ModelFormat,
+    ModelSettings,
+    MotionDefinition,
+} from "@doki-land/live2d-core";
+import { detectModelSettingsFormat } from "@doki-land/live2d-core";
+import {
+    fetchArrayBufferWithProgress,
+    fetchJsonWithProgress,
+} from "./fetch-progress.js";
+
+/** Resolve a relative asset URL against the model settings URL. */
+export function resolveAssetUrl(baseUrl: string, relative: string): string {
+    if (/^(?:[a-z]+:)?\/\//i.test(relative) || relative.startsWith("data:")) {
+        return relative;
+    }
+    try {
+        return new URL(relative, baseUrl).href;
+    } catch {
+        const slash = baseUrl.lastIndexOf("/");
+        const dir = slash >= 0 ? baseUrl.slice(0, slash + 1) : "";
+        return `${dir}${relative}`;
+    }
+}
+
+export interface UrlAssetResolverOptions {
+    onBytesProgress?: (
+        key: AssetKey,
+        update: { bytesLoaded: number; bytesTotal: number | null },
+    ) => void;
+}
+
+export function createUrlAssetResolver(
+    baseUrl: string,
+    options: UrlAssetResolverOptions = {},
+): AssetResolver {
+    return {
+        baseUrl,
+        resolve(key: AssetKey) {
+            return resolveAssetUrl(baseUrl, key);
+        },
+        async fetchJson(key: AssetKey) {
+            const url = resolveAssetUrl(baseUrl, key);
+            return fetchJsonWithProgress(url, (update) => {
+                options.onBytesProgress?.(key, update);
+            });
+        },
+        async fetchBytes(key: AssetKey) {
+            const url = resolveAssetUrl(baseUrl, key);
+            return fetchArrayBufferWithProgress(url, (update) => {
+                options.onBytesProgress?.(key, update);
+            });
+        },
+    };
+}
+
+export interface LoadPipelineContext {
+    source: string;
+    json?: unknown;
+    format?: ModelFormat;
+    settings?: ModelSettings;
+}
+
+export type LoadMiddleware = (
+    ctx: LoadPipelineContext,
+    next: () => Promise<void>,
+) => Promise<void>;
+
+export async function runLoadPipeline(
+    ctx: LoadPipelineContext,
+    middlewares: LoadMiddleware[],
+): Promise<LoadPipelineContext> {
+    let index = 0;
+    const dispatch = async (): Promise<void> => {
+        const mw = middlewares[index++];
+        if (!mw) return;
+        await mw(ctx, dispatch);
+    };
+    await dispatch();
+    return ctx;
+}
+
+/** Fetch model settings JSON from a URL. */
+export async function fetchModelJson(
+    url: string,
+    onProgress?: (update: {
+        bytesLoaded: number;
+        bytesTotal: number | null;
+    }) => void,
+): Promise<unknown> {
+    return fetchJsonWithProgress(url, onProgress);
+}
+
+/** Detect moc2 vs moc3 from settings JSON shape (core helper; throws if unknown). */
+export function detectModelFormat(json: unknown): ModelFormat {
+    if (!json || typeof json !== "object") {
+        throw new Error(
+            "@doki-land/live2d-loader: model json must be an object",
+        );
+    }
+    const format = detectModelSettingsFormat(json);
+    if (!format) {
+        throw new Error(
+            "@doki-land/live2d-loader: unrecognized Live2D model json",
+        );
+    }
+    return format;
+}
+
+function asStringArray(value: unknown): string[] {
+    if (!Array.isArray(value)) return [];
+    return value.filter((v): v is string => typeof v === "string");
+}
+
+/** Normalize raw model3.json / model.json into ModelSettings. */
+export function normalizeModelSettings(
+    json: unknown,
+    url: string,
+): ModelSettings {
+    const format = detectModelFormat(json);
+    const o = json as Record<string, unknown>;
+
+    if (format === "moc3") {
+        const fileRefs = o.FileReferences as Record<string, unknown>;
+        const moc = fileRefs.Moc as string;
+        const textures = asStringArray(fileRefs.Textures);
+        const motionGroups: Record<string, MotionDefinition[]> = {};
+        const motions = fileRefs.Motions;
+        if (motions && typeof motions === "object") {
+            for (const [group, list] of Object.entries(
+                motions as Record<string, unknown>,
+            )) {
+                if (!Array.isArray(list)) continue;
+                motionGroups[group] = list
+                    .map((item) => {
+                        if (!item || typeof item !== "object") return null;
+                        const file = (item as Record<string, unknown>).File;
+                        if (typeof file !== "string") return null;
+                        const def: MotionDefinition = { file };
+                        const sound = (item as Record<string, unknown>).Sound;
+                        if (typeof sound === "string") def.sound = sound;
+                        const fadeIn = (item as Record<string, unknown>)
+                            .FadeInTime;
+                        if (typeof fadeIn === "number") def.fadeInTime = fadeIn;
+                        const fadeOut = (item as Record<string, unknown>)
+                            .FadeOutTime;
+                        if (typeof fadeOut === "number")
+                            def.fadeOutTime = fadeOut;
+                        return def;
+                    })
+                    .filter((x): x is MotionDefinition => x !== null);
+            }
+        }
+        const expressions: ExpressionDefinition[] = [];
+        const expr = fileRefs.Expressions;
+        if (Array.isArray(expr)) {
+            for (const item of expr) {
+                if (!item || typeof item !== "object") continue;
+                const name = (item as Record<string, unknown>).Name;
+                const file = (item as Record<string, unknown>).File;
+                if (typeof name === "string" && typeof file === "string") {
+                    expressions.push({ name, file });
+                }
+            }
+        }
+        const hitAreas: HitAreaDefinition[] = [];
+        if (Array.isArray(o.HitAreas)) {
+            for (const item of o.HitAreas) {
+                if (!item || typeof item !== "object") continue;
+                const name = (item as Record<string, unknown>).Name;
+                const id = (item as Record<string, unknown>).Id;
+                if (typeof name === "string" && typeof id === "string") {
+                    hitAreas.push({ name, id });
+                }
+            }
+        }
+        return {
+            format: "moc3",
+            url,
+            name: typeof o.Name === "string" ? o.Name : undefined,
+            moc,
+            textures,
+            motionGroups,
+            expressions,
+            physics:
+                typeof fileRefs.Physics === "string"
+                    ? fileRefs.Physics
+                    : undefined,
+            pose: typeof fileRefs.Pose === "string" ? fileRefs.Pose : undefined,
+            hitAreas,
+        };
+    }
+
+    // moc2
+    return {
+        format: "moc2",
+        url,
+        moc: o.model as string,
+        textures: asStringArray(o.textures),
+        motionGroups: {},
+        expressions: [],
+        hitAreas: [],
+    };
+}

package/src/resolve-source.ts

@@ -0,0 +1,111 @@
+/**
+ * Resolve model settings URLs, including `npm:` specifiers via a CDN.
+ */
+
+const DEFAULT_NPM_CDN = "https://cdn.jsdelivr.net/npm";
+
+export interface ResolveModelSourceOptions {
+    /** Default: `https://cdn.jsdelivr.net/npm` */
+    npmCdnBase?: string;
+}
+
+/**
+ * Parse `name@version/path`, `@scope/name@version/path`, or `name/path`.
+ * When version is omitted, jsDelivr resolves the latest published version.
+ */
+export function resolveNpmSpecifier(
+    spec: string,
+    cdnBase: string = DEFAULT_NPM_CDN,
+): string {
+    const trimmed = spec.trim().replace(/^\/+/, "");
+    if (!trimmed) {
+        throw new Error("@doki-land/live2d-loader: empty npm model specifier");
+    }
+
+    let pkg = "";
+    let version: string | null = null;
+    let assetPath = "";
+
+    if (trimmed.startsWith("@")) {
+        // @scope/name[@version][/path]
+        const scopeSlash = trimmed.indexOf("/");
+        if (scopeSlash < 0) {
+            throw new Error(
+                `@doki-land/live2d-loader: scoped npm specifier needs /name: ${spec}`,
+            );
+        }
+        const afterScope = trimmed.slice(scopeSlash + 1);
+        const at = afterScope.indexOf("@");
+        const slash = afterScope.indexOf("/");
+        if (at >= 0 && (slash < 0 || at < slash)) {
+            pkg = `${trimmed.slice(0, scopeSlash + 1)}${afterScope.slice(0, at)}`;
+            const rest = afterScope.slice(at + 1);
+            const pathSlash = rest.indexOf("/");
+            if (pathSlash < 0) {
+                version = rest;
+            } else {
+                version = rest.slice(0, pathSlash);
+                assetPath = rest.slice(pathSlash + 1);
+            }
+        } else if (slash >= 0) {
+            pkg = `${trimmed.slice(0, scopeSlash + 1)}${afterScope.slice(0, slash)}`;
+            assetPath = afterScope.slice(slash + 1);
+        } else {
+            pkg = trimmed;
+        }
+    } else {
+        const at = trimmed.indexOf("@");
+        const slash = trimmed.indexOf("/");
+        if (at >= 0 && (slash < 0 || at < slash)) {
+            pkg = trimmed.slice(0, at);
+            const rest = trimmed.slice(at + 1);
+            const pathSlash = rest.indexOf("/");
+            if (pathSlash < 0) {
+                version = rest;
+            } else {
+                version = rest.slice(0, pathSlash);
+                assetPath = rest.slice(pathSlash + 1);
+            }
+        } else if (slash >= 0) {
+            pkg = trimmed.slice(0, slash);
+            assetPath = trimmed.slice(slash + 1);
+        } else {
+            pkg = trimmed;
+        }
+    }
+
+    if (!pkg) {
+        throw new Error(
+            `@doki-land/live2d-loader: invalid npm model specifier: ${spec}`,
+        );
+    }
+    if (!assetPath) {
+        throw new Error(
+            `@doki-land/live2d-loader: npm model specifier needs an asset path (got "${spec}")`,
+        );
+    }
+
+    const base = cdnBase.replace(/\/+$/, "");
+    const nameWithVersion = version ? `${pkg}@${version}` : pkg;
+    return `${base}/${nameWithVersion}/${assetPath.replace(/^\/+/, "")}`;
+}
+
+/**
+ * Turn a model source string into a fetchable URL.
+ * - `npm:pkg[@ver]/path` → CDN URL (jsDelivr by default)
+ * - `http(s)://...` / absolute / relative paths pass through
+ */
+export function resolveModelSourceUrl(
+    source: string,
+    options: ResolveModelSourceOptions = {},
+): string {
+    if (source.startsWith("npm:")) {
+        return resolveNpmSpecifier(
+            source.slice("npm:".length),
+            options.npmCdnBase ?? DEFAULT_NPM_CDN,
+        );
+    }
+    return source;
+}
+
+export { DEFAULT_NPM_CDN };