@starcried/starlite-vrm 0.0.0-stage → 0.1.0-alpha.2

package/dist/playback.js

@@ -0,0 +1,122 @@
+var _a;
+import { AnimationMixer, AnimationClip, PropertyBinding, QuaternionKeyframeTrack, VectorKeyframeTrack, NumberKeyframeTrack, LoopOnce, LoopRepeat } from "three";
+/** One semantic clip, with a short captured-pose transition on interruption. */
+export class VrmAnimationPlayer {
+    mixer;
+    #clips;
+    #restore;
+    #returnTo;
+    #active;
+    #finished = false;
+    #transition;
+    static transitionSeconds = .4;
+    constructor(root, clips, restore, returnTo) {
+        if (returnTo && !clips.has(returnTo))
+            throw new Error(`return animation does not exist: ${returnTo}`);
+        this.mixer = new AnimationMixer(root);
+        this.#clips = clips;
+        this.#restore = restore;
+        this.#returnTo = returnTo;
+        this.mixer.addEventListener("finished", (event) => { if (event.action === this.#active?.action)
+            this.#finished = true; });
+    }
+    get activeName() { return this.#active?.name; }
+    get isOneShot() { return this.#active?.action.loop === LoopOnce; }
+    get hasLookAtTrack() { return this.#clips.get(this.#active?.name ?? "")?.tracks.some((track) => track.name.includes("LookAt")) ?? false; }
+    get hasBlinkTrack() { return this.#clips.get(this.#active?.name ?? "")?.tracks.some((track) => /VRMExpression_blink(?:Left|Right)?\.weight$/.test(track.name)) ?? false; }
+    play(name, options = {}) {
+        const clip = this.#clips.get(name);
+        if (!clip)
+            return Promise.reject(new Error(`animation does not exist: ${name}`));
+        if (this.#active?.name === name && !options.restart)
+            return this.#active.promise;
+        const pose = this.#active ? this.#capturePose() : undefined;
+        this.stop("interrupted");
+        const action = this.mixer.clipAction(clip).reset().setEffectiveWeight(1);
+        action.setLoop(options.mode === "loop" ? LoopRepeat : LoopOnce, options.mode === "loop" ? Infinity : 1);
+        action.clampWhenFinished = true;
+        let resolve;
+        const promise = new Promise((done) => { resolve = done; });
+        this.#active = { name, action, promise, resolve };
+        action.play();
+        if (pose) {
+            const outgoing = this.mixer.clipAction(pose);
+            outgoing.setLoop(LoopOnce, 1);
+            outgoing.clampWhenFinished = true;
+            outgoing.setEffectiveWeight(1).play();
+            action.setEffectiveWeight(0);
+            this.#transition = { clip: pose, action: outgoing, elapsed: 0 };
+        }
+        this.mixer.update(0);
+        return promise;
+    }
+    update(delta) {
+        if (this.#transition) {
+            this.#transition.elapsed += delta;
+            const t = Math.max(0, Math.min(1, this.#transition.elapsed / _a.transitionSeconds));
+            // Ease the blend at both ends without overshooting a bone's target pose.
+            // This shapes the weights; the frozen snapshot does not retain velocity.
+            const weight = t * t * (3 - 2 * t);
+            this.#transition.action.setEffectiveWeight(1 - weight);
+            this.#active?.action.setEffectiveWeight(weight);
+        }
+        this.mixer.update(delta);
+        if (this.#transition && this.#transition.elapsed >= _a.transitionSeconds)
+            this.#clearTransition();
+        if (this.#finished) {
+            if (this.#returnTo) {
+                // Finish at the authored endpoint, then capture it before starting Idle.
+                // Restoring neutral first would erase the pose needed for the exit blend.
+                this.#active?.resolve("completed");
+                void this.play(this.#returnTo, { mode: "loop", restart: true });
+            }
+            else
+                this.stop("completed");
+        }
+    }
+    stop(result = "stopped") {
+        const active = this.#active;
+        this.#active = undefined;
+        this.#finished = false;
+        this.#clearTransition();
+        this.mixer.stopAllAction();
+        this.#restore();
+        active?.resolve(result);
+    }
+    #capturePose() {
+        // Capture the currently mixed pose, including an interrupted transition.
+        // Freezing this snapshot avoids a neutral-frame snap or unbounded outgoing
+        // actions when DSH changes state several times inside the transition.
+        const tracks = new Map();
+        for (const clip of this.#clips.values()) {
+            for (const source of clip.tracks) {
+                if (tracks.has(source.name))
+                    continue;
+                const Track = source.ValueTypeName === "quaternion" ? QuaternionKeyframeTrack
+                    : source.ValueTypeName === "vector" ? VectorKeyframeTrack : NumberKeyframeTrack;
+                const size = source.ValueTypeName === "quaternion" ? 4 : source.ValueTypeName === "vector" ? 3 : 1;
+                const value = new Float32Array(size);
+                const binding = new PropertyBinding(this.mixer.getRoot(), source.name);
+                // Three assigns this getter dynamically when the binding is bound;
+                // its type declarations only expose bind/unbind.
+                binding.bind();
+                binding.getValue(value, 0);
+                binding.unbind();
+                // A snapshot is always constant, even if the source used GLTF cubic
+                // splines with tangent triplets and a custom interpolant factory.
+                const track = new Track(source.name, [0, _a.transitionSeconds], [...value, ...value]);
+                tracks.set(track.name, track);
+            }
+        }
+        return new AnimationClip("transition-pose", _a.transitionSeconds, [...tracks.values()]);
+    }
+    #clearTransition() {
+        if (!this.#transition)
+            return;
+        this.#transition.action.stop();
+        this.mixer.uncacheClip(this.#transition.clip);
+        this.#transition = undefined;
+    }
+    destroy() { this.stop(); this.mixer.uncacheRoot(this.mixer.getRoot()); }
+}
+_a = VrmAnimationPlayer;

package/dist/pose-bounds.d.ts

@@ -0,0 +1,8 @@
+import { Box3, type Object3D } from "three";
+/** Conservative skin bounds: build vertex clusters once, then transform one box
+ * per influencing bone. This avoids reskinning every vertex on every frame. */
+export declare class PoseBounds {
+    #private;
+    constructor(root: Object3D);
+    measure(root: Object3D, result?: Box3): Box3;
+}

package/dist/pose-bounds.js

@@ -0,0 +1,80 @@
+import { Box3, Matrix3, Matrix4, Mesh, SkinnedMesh, Vector3 } from "three";
+/** Conservative skin bounds: build vertex clusters once, then transform one box
+ * per influencing bone. This avoids reskinning every vertex on every frame. */
+export class PoseBounds {
+    #meshes = [];
+    #matrix = new Matrix4();
+    #box = new Box3();
+    constructor(root) {
+        const point = new Vector3(), local = new Vector3(), offset = new Vector3(), matrix = new Matrix4(), linear = new Matrix3();
+        root.traverseVisible(object => {
+            if (!(object instanceof Mesh))
+                return;
+            const mesh = object, geometry = mesh.geometry, positions = geometry.getAttribute("position");
+            if (!positions)
+                return;
+            const boxes = new Map();
+            const skin = mesh instanceof SkinnedMesh;
+            const indices = geometry.getAttribute("skinIndex"), weights = geometry.getAttribute("skinWeight");
+            for (let vertex = 0; vertex < positions.count; vertex++) {
+                point.fromBufferAttribute(positions, vertex);
+                if (skin && (!indices || !weights))
+                    throw new Error("skin bounds require joint indices and weights");
+                for (let axis = 0; axis < (skin ? 4 : 1); axis++) {
+                    if (skin && weights.getComponent(vertex, axis) <= 0)
+                        continue;
+                    const joint = skin ? indices.getComponent(vertex, axis) : -1;
+                    matrix.identity();
+                    if (skin) {
+                        const inverse = mesh.skeleton.boneInverses[joint];
+                        if (!inverse)
+                            throw new Error("skin bounds reference a missing joint");
+                        matrix.copy(inverse).multiply(mesh.bindMatrix);
+                    }
+                    linear.setFromMatrix4(matrix);
+                    const box = boxes.get(joint) ?? { base: new Box3(), morphs: new Map() };
+                    box.base.expandByPoint(local.copy(point).applyMatrix4(matrix));
+                    for (const [index, morph] of (geometry.morphAttributes.position ?? []).entries()) {
+                        offset.fromBufferAttribute(morph, vertex);
+                        if (!geometry.morphTargetsRelative)
+                            offset.sub(point);
+                        if (offset.lengthSq() === 0)
+                            continue;
+                        offset.applyMatrix3(linear);
+                        // Include zero: other vertices in this cluster may not use a morph.
+                        const delta = box.morphs.get(index) ?? new Box3(new Vector3(), new Vector3());
+                        delta.expandByPoint(offset);
+                        box.morphs.set(index, delta);
+                    }
+                    boxes.set(joint, box);
+                }
+            }
+            this.#meshes.push({ mesh, boxes });
+        });
+    }
+    measure(root, result = new Box3()) {
+        root.updateMatrixWorld(true);
+        result.makeEmpty();
+        for (const { mesh, boxes } of this.#meshes) {
+            if (!mesh.visible)
+                continue;
+            for (const [joint, box] of boxes) {
+                this.#matrix.copy(mesh.matrixWorld);
+                if (mesh instanceof SkinnedMesh)
+                    this.#matrix.multiply(mesh.bindMatrixInverse).multiply(mesh.skeleton.bones[joint].matrixWorld);
+                this.#box.copy(box.base);
+                // Only active morphs contribute, rather than sizing the camera for all
+                // mutually exclusive facial expressions simultaneously.
+                for (const [index, delta] of box.morphs) {
+                    const weight = mesh.morphTargetInfluences?.[index] ?? 0;
+                    if (!Number.isFinite(weight))
+                        throw new Error("non-finite morph weight");
+                    this.#box.min.addScaledVector(weight < 0 ? delta.max : delta.min, weight);
+                    this.#box.max.addScaledVector(weight < 0 ? delta.min : delta.max, weight);
+                }
+                result.union(this.#box.applyMatrix4(this.#matrix));
+            }
+        }
+        return result;
+    }
+}

package/dist/prepare.cjs

@@ -0,0 +1,387 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/prepare.ts
+var prepare_exports = {};
+__export(prepare_exports, {
+  prepareModel: () => prepareModel,
+  readPreparedBundle: () => readPreparedBundle,
+  readPreparedBundleSync: () => readPreparedBundleSync
+});
+module.exports = __toCommonJS(prepare_exports);
+var import_node_fs = require("node:fs");
+var import_node_crypto = require("node:crypto");
+var import_promises = require("node:fs/promises");
+var import_node_path = require("node:path");
+
+// src/inspect.ts
+var MAX_MODEL_BYTES = 64 * 1024 * 1024;
+var MAX_ANIMATION_BYTES = 16 * 1024 * 1024;
+function parseGlb(bytes, kind) {
+  const limit = kind === "vrm" ? MAX_MODEL_BYTES : MAX_ANIMATION_BYTES;
+  if (bytes.byteLength < 20 || bytes.byteLength > limit) throw new Error("invalid GLB size");
+  const view = new DataView(bytes);
+  if (view.getUint32(0, true) !== 1179937895 || view.getUint32(4, true) !== 2 || view.getUint32(8, true) !== bytes.byteLength) throw new Error("invalid GLB header");
+  let json;
+  let binSize = 0;
+  let binStart = 0;
+  let chunkCount = 0;
+  for (let offset = 12; offset < bytes.byteLength; ) {
+    if (offset + 8 > bytes.byteLength) throw new Error("truncated GLB chunk");
+    const size = view.getUint32(offset, true), type = view.getUint32(offset + 4, true);
+    offset += 8;
+    if (size % 4 || size > bytes.byteLength - offset) throw new Error("invalid GLB chunk length");
+    if (chunkCount === 0 && type === 1313821514) {
+      json = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(new Uint8Array(bytes, offset, size)));
+    } else if (chunkCount === 1 && type === 5130562) {
+      binSize = size;
+      binStart = offset;
+    } else throw new Error("unexpected GLB chunk");
+    offset += size;
+    chunkCount++;
+  }
+  if (!json || json.asset?.version !== "2.0") throw new Error("glTF 2.0 is required");
+  const expected = kind === "vrm" ? json.extensions?.VRM ?? json.extensions?.VRMC_vrm : json.extensions?.VRMC_vrm_animation;
+  if (!expected) throw new Error(`missing ${kind} extension`);
+  if (kind === "vrm" && json.extensions?.VRM && json.extensions.VRM.specVersion !== "0.0") throw new Error("unsupported VRM version");
+  if (kind === "vrm" && json.extensions?.VRMC_vrm && json.extensions.VRMC_vrm.specVersion !== "1.0") throw new Error("unsupported VRM version");
+  if (kind === "vrma" && expected.specVersion !== "1.0") throw new Error("VRMA 1.0 is required");
+  const allowed = /* @__PURE__ */ new Set(["VRM", "VRMC_vrm", "VRMC_vrm_animation", "VRMC_materials_mtoon", "VRMC_springBone", "VRMC_node_constraint", "VRMC_materials_hdr_emissiveMultiplier", "KHR_materials_unlit", "KHR_texture_transform", "KHR_materials_emissive_strength"]);
+  if ((json.extensionsRequired ?? []).some((name) => !allowed.has(name))) throw new Error("unsupported required glTF extension");
+  const visit = (value, depth = 0) => {
+    if (depth > 64) throw new Error("glTF nesting limit exceeded");
+    if (!value || typeof value !== "object") return;
+    for (const [key, child] of Object.entries(value)) {
+      if (key === "uri") throw new Error("external glTF resources are not supported");
+      if (typeof child === "number" && !Number.isFinite(child)) throw new Error("non-finite glTF value");
+      visit(child, depth + 1);
+    }
+  };
+  visit(json);
+  if ((json.buffers?.length ?? 0) > 1 || (json.buffers?.[0]?.byteLength ?? 0) > binSize) throw new Error("invalid GLB buffer");
+  for (const buffer of json.bufferViews ?? []) {
+    const start = buffer.byteOffset ?? 0, length = buffer.byteLength;
+    if (buffer.buffer !== 0 || !Number.isSafeInteger(start) || !Number.isSafeInteger(length) || start < 0 || length < 0 || start + length > (json.buffers?.[0]?.byteLength ?? 0)) throw new Error("invalid glTF buffer view");
+  }
+  if ((json.nodes?.length ?? 0) > 4096 || (json.accessors?.length ?? 0) > 32768) throw new Error("glTF resource count exceeded");
+  validateStructure(json, new DataView(bytes, binStart, binSize));
+  return json;
+}
+function embeddedAnimationCatalog(json) {
+  const animations = json.animations ?? [];
+  if (!Array.isArray(animations) || animations.length > 64) throw new Error("at most 64 embedded animations are supported");
+  const names = /* @__PURE__ */ new Set();
+  return animations.map((animation, index) => {
+    const name = animation.name ?? "Animation_" + (index + 1);
+    if (typeof name !== "string" || !name.trim() || new TextEncoder().encode(name).length > 128 || /[\u0000-\u001f\u007f]/.test(name) || name === "StarLiteIdle" || names.has(name)) throw new Error("invalid or duplicate embedded animation name");
+    names.add(name);
+    let duration = 0;
+    for (const sampler of animation.samplers ?? []) {
+      const accessor = json.accessors?.[sampler.input];
+      if (!accessor || accessor.type !== "SCALAR" || accessor.componentType !== 5126 || !Number.isFinite(accessor.max?.[0])) throw new Error("embedded animation has invalid animation times");
+      duration = Math.max(duration, accessor.max[0]);
+    }
+    if (!(duration > 0) || duration > 600) throw new Error("embedded animation duration must be between 0 and 600 seconds");
+    return { name, durationMs: duration * 1e3 };
+  });
+}
+function inspectVrm(bytes) {
+  const json = parseGlb(bytes, "vrm");
+  const v0 = json.extensions.VRM;
+  const humanoid = (v0 ?? json.extensions.VRMC_vrm).humanoid?.humanBones;
+  const bones = v0 ? Object.fromEntries((humanoid ?? []).map((b) => [b.bone, b])) : humanoid;
+  const required = ["hips", "spine", "head", ...["left", "right"].flatMap((side) => ["UpperLeg", "LowerLeg", "Foot", "UpperArm", "LowerArm", "Hand"].map((part) => side + part))];
+  const used = /* @__PURE__ */ new Set();
+  for (const name2 of required) {
+    const node = bones?.[name2]?.node;
+    if (!Number.isSafeInteger(node) || !json.nodes?.[node] || used.has(node)) throw new Error("invalid required humanoid bone");
+    used.add(node);
+  }
+  const blinkNames = v0 ? ["blink", "blink_l", "blink_r"] : ["blink", "blinkLeft", "blinkRight"];
+  const groups = v0?.blendShapeMaster?.blendShapeGroups;
+  if (groups !== void 0 && !Array.isArray(groups)) throw new Error("invalid VRM blink expressions");
+  const blinkPresets = v0 ? (groups ?? []).filter((item) => blinkNames.includes(item?.presetName)) : blinkNames.flatMap((name2) => {
+    const expression = json.extensions.VRMC_vrm.expressions?.preset?.[name2];
+    return expression === void 0 ? [] : [expression];
+  });
+  for (const expression of blinkPresets) {
+    if (!expression || typeof expression !== "object" || Array.isArray(expression)) throw new Error("invalid VRM blink expression");
+    const binds = v0 ? expression.binds : expression.morphTargetBinds;
+    if (binds === void 0) continue;
+    if (!Array.isArray(binds)) throw new Error("invalid VRM blink bindings");
+    for (const bind of binds) {
+      const mesh = v0 ? bind?.mesh : json.nodes?.[bind?.node]?.mesh;
+      const primitives = json.meshes?.[mesh]?.primitives;
+      if (!bind || !Number.isSafeInteger(mesh) || mesh < 0 || !v0 && (!Number.isSafeInteger(bind.node) || bind.node < 0) || !Number.isSafeInteger(bind.index) || bind.index < 0 || !Number.isFinite(bind.weight) || bind.weight < 0 || bind.weight > (v0 ? 100 : 1) || !Array.isArray(primitives) || !primitives.some((primitive) => primitive.targets?.[bind.index] !== void 0)) {
+        throw new Error("invalid VRM blink morph binding");
+      }
+    }
+  }
+  const meta = (v0 ?? json.extensions.VRMC_vrm).meta ?? {};
+  const name = v0 ? meta.title : meta.name;
+  return {
+    version: v0 ? "0" : "1",
+    ...typeof name === "string" ? { name } : {},
+    animations: embeddedAnimationCatalog(json),
+    expressions: v0 ? (v0.blendShapeMaster?.blendShapeGroups ?? []).map((group) => group.name) : Object.keys({ ...json.extensions.VRMC_vrm.expressions?.preset, ...json.extensions.VRMC_vrm.expressions?.custom })
+  };
+}
+function inspectVrma(bytes) {
+  const json = parseGlb(bytes, "vrma");
+  if (json.animations?.length !== 1) throw new Error("each VRMA file must contain exactly one animation");
+  let duration = 0;
+  for (const sampler of json.animations[0].samplers ?? []) {
+    const accessor = json.accessors?.[sampler.input];
+    if (!accessor || accessor.type !== "SCALAR" || accessor.componentType !== 5126 || !Number.isFinite(accessor.max?.[0])) throw new Error("VRMA has invalid animation times");
+    duration = Math.max(duration, accessor.max[0]);
+  }
+  if (!(duration > 0) || duration > 600) throw new Error("VRMA duration must be between 0 and 600 seconds");
+  return { durationMs: duration * 1e3 };
+}
+function validateStructure(json, binary) {
+  for (const key of ["nodes", "accessors", "bufferViews", "buffers", "meshes", "images", "animations", "skins", "scenes"]) {
+    if (json[key] !== void 0 && !Array.isArray(json[key])) throw new Error(`invalid glTF ${key}`);
+  }
+  const views = json.bufferViews ?? [], nodes = json.nodes ?? [], accessors = json.accessors ?? [];
+  const integer = (n, min, max) => Number.isSafeInteger(n) && n >= min && n <= max;
+  const index = (n, array) => integer(n, 0, array.length - 1);
+  const seen = /* @__PURE__ */ new Set(), active = /* @__PURE__ */ new Set(), parents = /* @__PURE__ */ new Set();
+  const walk = (i, depth) => {
+    if (!index(i, nodes) || active.has(i) || depth > 128) throw new Error("invalid glTF node hierarchy");
+    if (seen.has(i)) return;
+    const node = nodes[i];
+    if (!node || typeof node !== "object") throw new Error("invalid glTF node");
+    seen.add(i);
+    active.add(i);
+    if (node.children !== void 0 && !Array.isArray(node.children)) throw new Error("invalid node children");
+    for (const child of node.children ?? []) {
+      if (parents.has(child)) throw new Error("node has multiple parents");
+      parents.add(child);
+      walk(child, depth + 1);
+    }
+    active.delete(i);
+  };
+  for (let i = 0; i < nodes.length; i++) walk(i, 0);
+  const components = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 };
+  const sizes = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 };
+  let decoded = 0;
+  const span = (viewIndex, offset, count, element, alignment, strided = false) => {
+    if (!index(viewIndex, views)) throw new Error("invalid accessor buffer view");
+    const v = views[viewIndex], stride = strided ? v.byteStride ?? element : element;
+    if (!integer(offset, 0, v.byteLength) || offset % alignment || !integer(stride, element, 256) || stride % alignment || offset + (count - 1) * stride + element > v.byteLength) throw new Error("accessor exceeds buffer view");
+    return (v.byteOffset ?? 0) + offset;
+  };
+  for (const a of accessors) {
+    const width = sizes[a?.componentType], count = a?.count, componentsCount = components[a?.type];
+    if (!width || !componentsCount || !integer(count, 1, 2e6)) throw new Error("invalid accessor allocation");
+    const dimension = a.type === "MAT2" ? 2 : a.type === "MAT3" ? 3 : a.type === "MAT4" ? 4 : 0;
+    const element = dimension ? Math.ceil(dimension * width / 4) * 4 * dimension : width * componentsCount;
+    decoded += element * count;
+    if (decoded > 256 * 1024 * 1024) throw new Error("decoded geometry exceeds 256 MiB");
+    const checkFloats = (at, n, stride) => {
+      if (a.componentType !== 5126) return;
+      for (let k = 0; k < n; k++) for (let c = 0; c < componentsCount; c++) if (!Number.isFinite(binary.getFloat32(at + k * stride + c * 4, true))) throw new Error("non-finite accessor value");
+    };
+    if (a.bufferView !== void 0) {
+      const at = span(a.bufferView, a.byteOffset ?? 0, count, element, width, true);
+      checkFloats(at, count, views[a.bufferView].byteStride ?? element);
+    }
+    if (a.sparse) {
+      const sparse = a.sparse, n = sparse.count, iw = sizes[sparse.indices?.componentType];
+      if (!integer(n, 1, count) || ![5121, 5123, 5125].includes(sparse.indices?.componentType)) throw new Error("invalid sparse accessor");
+      const at = span(sparse.indices.bufferView, sparse.indices.byteOffset ?? 0, n, iw, iw);
+      const valuesAt = span(sparse.values?.bufferView, sparse.values?.byteOffset ?? 0, n, element, width);
+      checkFloats(valuesAt, n, element);
+      let previous = -1;
+      for (let k = 0; k < n; k++) {
+        const offset = at + k * iw;
+        const next = iw === 1 ? binary.getUint8(offset) : iw === 2 ? binary.getUint16(offset, true) : binary.getUint32(offset, true);
+        if (next <= previous || next >= count) throw new Error("invalid sparse index");
+        previous = next;
+      }
+    }
+  }
+  for (const animation of json.animations ?? []) {
+    if (!Array.isArray(animation.samplers) || !Array.isArray(animation.channels)) throw new Error("invalid animation");
+    for (const channel of animation.channels) {
+      if (!index(channel.sampler, animation.samplers) || !index(channel.target?.node, nodes) || !["translation", "rotation", "scale", "weights"].includes(channel.target?.path)) throw new Error("invalid animation channel");
+    }
+    for (const sampler of animation.samplers) {
+      if (!index(sampler.input, accessors) || !index(sampler.output, accessors)) throw new Error("invalid animation accessor");
+      const a = accessors[sampler.input];
+      if (a.type !== "SCALAR" || a.componentType !== 5126 || a.sparse || a.bufferView === void 0) throw new Error("invalid animation timeline");
+      const start = span(a.bufferView, a.byteOffset ?? 0, a.count, 4, 4);
+      let previous = -1;
+      for (let i = 0; i < a.count; i++) {
+        const time = binary.getFloat32(start + i * 4, true);
+        if (!Number.isFinite(time) || time <= previous || time < 0 || time > 600) throw new Error("invalid animation times");
+        previous = time;
+      }
+      if (!Array.isArray(a.max) || Math.abs(a.max[0] - previous) > 1e-3) throw new Error("animation duration does not match timeline");
+      if (sampler.interpolation !== void 0 && !["LINEAR", "STEP", "CUBICSPLINE"].includes(sampler.interpolation)) throw new Error("unsupported animation interpolation");
+    }
+  }
+}
+
+// src/config.ts
+function finite(value, min, max) {
+  return typeof value === "number" && Number.isFinite(value) && value >= min && value <= max;
+}
+function validateCharacterProfile(input) {
+  if (!input || typeof input !== "object") throw new Error("invalid character profile");
+  const profile = input;
+  if (profile.schemaVersion !== 1 || profile.type !== "weiguang") throw new Error("unsupported character profile");
+  const record = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+  const pose = (value) => {
+    if (!record(value) || Object.keys(value).length > 256) return false;
+    return Object.values(value).every((item) => Array.isArray(item?.rotation) && item.rotation.length === 4 && item.rotation.every((v) => finite(v, -1, 1)) && Math.abs(Math.hypot(...item.rotation) - 1) < 0.01 && (item.position === void 0 || Array.isArray(item.position) && item.position.length === 3 && item.position.every((v) => finite(v, -10, 10))));
+  };
+  if (!pose(profile.neutralPose) || !record(profile.earPoses) || !Object.values(profile.earPoses).every(pose)) throw new Error("invalid character bone poses");
+  if (!Array.isArray(profile.earBones) || profile.earBones.length > 32 || profile.earBones.some((name) => typeof name !== "string" || !name)) throw new Error("invalid ear bones");
+  if (!record(profile.expressions) || Object.keys(profile.expressions).length > 64 || !Object.values(profile.expressions).every((v) => typeof v?.expression === "string" && (v.blink === void 0 || typeof v.blink === "string"))) throw new Error("invalid expressions");
+  if (profile.neutralAnimation !== void 0 && (typeof profile.neutralAnimation !== "string" || !profile.neutralAnimation.trim() || profile.neutralAnimation.length > 128)) throw new Error("invalid neutral animation");
+  for (const emotion of ["Neutral", ...Object.keys(profile.expressions)]) if (!profile.earPoses[emotion] || profile.earBones.some((name) => !profile.earPoses[emotion]?.[name])) throw new Error("incomplete ear poses");
+  const a = profile.accessories;
+  if (!a || typeof a.collar !== "string" || typeof a.cone !== "string" || typeof a.collarVisible !== "boolean" || typeof a.coneVisible !== "boolean") throw new Error("invalid accessories");
+  const blink = profile.blink;
+  if (!blink || !finite(blink.period, 1, 60) || !Array.isArray(blink.curve) || blink.curve.length < 2 || blink.curve.length > 64) throw new Error("invalid blink timing");
+  let previous = -1;
+  for (const point of blink.curve) {
+    if (!Array.isArray(point) || point.length !== 2 || !finite(point[0], 0, blink.period) || point[0] <= previous || !finite(point[1], 0, 1)) throw new Error("invalid blink curve");
+    previous = point[0];
+  }
+}
+
+// src/prepare.ts
+var hash = (bytes) => (0, import_node_crypto.createHash)("sha256").update(bytes).digest("hex");
+var arrayBuffer = (bytes) => Uint8Array.from(bytes).buffer;
+async function bounded(path, maximum) {
+  const info = await (0, import_promises.lstat)(path);
+  if (!info.isFile() || info.size > maximum) throw new Error("invalid asset size or file type");
+  const bytes = await (0, import_promises.readFile)(path);
+  if (bytes.byteLength > maximum) throw new Error("asset exceeds byte limit");
+  return bytes;
+}
+function animationNames(animations) {
+  if (!Array.isArray(animations) || animations.length > 64) throw new Error("invalid animation collection");
+  const names = /* @__PURE__ */ new Set();
+  for (const a of animations) {
+    if (!a || typeof a.name !== "string" || !a.name.trim() || a.name.length > 128 || names.has(a.name)) throw new Error("duplicate or invalid animation name");
+    names.add(a.name);
+  }
+}
+function profileNames(profile, animations) {
+  if (profile.neutralAnimation && !animations.some((a) => a.name === profile.neutralAnimation)) throw new Error("profile neutral animation is missing");
+}
+async function prepareModel(request) {
+  const bytes = await bounded(request.model, MAX_MODEL_BYTES);
+  const inspected = inspectVrm(arrayBuffer(bytes));
+  const animations = request.animations ?? [];
+  animationNames(animations);
+  const files = /* @__PURE__ */ new Map([["model.vrm", bytes]]);
+  const record = (file, data) => ({ file, sha256: hash(data), bytes: data.byteLength });
+  const manifest = { schemaVersion: 1, tool: "vrm-companion-assets", backend: "vrm", model: { ...record("model.vrm", bytes), sourceSha256: hash(bytes) }, animations: [], publication: { allowRedistribution: request.allowRedistribution === true } };
+  let total = 0;
+  for (const [i, source] of animations.entries()) {
+    const data = await bounded(source.path, MAX_ANIMATION_BYTES);
+    total += data.byteLength;
+    if (total > 64 * 1024 * 1024) throw new Error("animation collection exceeds 64 MiB");
+    const { durationMs } = inspectVrma(arrayBuffer(data));
+    const file = `motions/${i}.vrma`;
+    files.set(file, data);
+    manifest.animations.push({ ...record(file, data), name: source.name, durationMs });
+  }
+  if (request.profile) {
+    const data = await bounded(request.profile, 1024 * 1024);
+    const profile = JSON.parse(data.toString("utf8"));
+    validateCharacterProfile(profile);
+    profileNames(profile, [...animations, ...inspected.animations, { name: "StarLiteIdle" }]);
+    files.set("profile.json", data);
+    manifest.profile = record("profile.json", data);
+  }
+  const output = (0, import_node_path.resolve)(request.output);
+  await (0, import_promises.mkdir)((0, import_node_path.dirname)(output), { recursive: true });
+  try {
+    await (0, import_promises.lstat)(output);
+    throw new Error("output already exists");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const stage = await (0, import_promises.mkdtemp)((0, import_node_path.join)((0, import_node_path.dirname)(output), ".vrm-stage-"));
+  try {
+    for (const [file, data] of files) {
+      const path = (0, import_node_path.join)(stage, file);
+      await (0, import_promises.mkdir)((0, import_node_path.dirname)(path), { recursive: true });
+      await (0, import_promises.writeFile)(path, data, { flag: "wx" });
+    }
+    await (0, import_promises.writeFile)((0, import_node_path.join)(stage, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", { flag: "wx" });
+    await (0, import_promises.rename)(stage, output);
+    return manifest;
+  } catch (error) {
+    await (0, import_promises.rm)(stage, { recursive: true, force: true });
+    throw error;
+  }
+}
+async function readPreparedBundle(directory) {
+  return readPreparedBundleSync(directory);
+}
+function boundedSync(path, maximum) {
+  const info = (0, import_node_fs.lstatSync)(path);
+  if (!info.isFile() || info.size > maximum) throw new Error("invalid asset size or file type");
+  const bytes = (0, import_node_fs.readFileSync)(path);
+  if (bytes.byteLength > maximum) throw new Error("asset exceeds byte limit");
+  return bytes;
+}
+function readPreparedBundleSync(directory) {
+  const root = (0, import_node_fs.realpathSync)(directory), raw = boundedSync((0, import_node_path.join)(root, "manifest.json"), 1024 * 1024);
+  const manifest = JSON.parse(raw.toString("utf8"));
+  if (manifest.schemaVersion !== 1 || manifest.tool !== "vrm-companion-assets" || manifest.backend !== "vrm" || typeof manifest.publication?.allowRedistribution !== "boolean" || !/^[a-f0-9]{64}$/.test(manifest.model?.sourceSha256)) throw new Error("invalid VRM manifest");
+  animationNames(manifest.animations);
+  const files = /* @__PURE__ */ new Map();
+  const load = (item, maximum) => {
+    if (!item || typeof item.file !== "string" || !item.file || (0, import_node_path.isAbsolute)(item.file) || /[\\:?%#]/.test(item.file) || item.file.split("/").some((p) => !p || p === "." || p === "..") || files.has(item.file) || !/^[a-f0-9]{64}$/.test(item.sha256) || !Number.isSafeInteger(item.bytes) || item.bytes < 1 || item.bytes > maximum) throw new Error("invalid manifest asset");
+    const path = (0, import_node_fs.realpathSync)((0, import_node_path.join)(root, item.file)), part = (0, import_node_path.relative)(root, path);
+    if ((0, import_node_path.isAbsolute)(part) || part === ".." || part.startsWith("../") || part.startsWith("..\\")) throw new Error("manifest asset leaves bundle");
+    const bytes = boundedSync(path, maximum);
+    if (bytes.byteLength !== item.bytes || hash(bytes) !== item.sha256) throw new Error("manifest asset hash mismatch");
+    files.set(item.file, bytes);
+    return bytes;
+  };
+  const inspected = inspectVrm(arrayBuffer(load(manifest.model, MAX_MODEL_BYTES)));
+  let total = 0;
+  for (const item of manifest.animations) {
+    const bytes = load(item, MAX_ANIMATION_BYTES);
+    total += bytes.byteLength;
+    if (total > 64 * 1024 * 1024) throw new Error("animation collection exceeds 64 MiB");
+    const inspected2 = inspectVrma(arrayBuffer(bytes));
+    if (!Number.isFinite(item.durationMs) || Math.abs(inspected2.durationMs - item.durationMs) > 1) throw new Error("manifest animation duration mismatch");
+  }
+  if (manifest.profile) {
+    const bytes = load(manifest.profile, 1024 * 1024);
+    const profile = JSON.parse(bytes.toString("utf8"));
+    validateCharacterProfile(profile);
+    profileNames(profile, [...manifest.animations, ...inspected.animations, { name: "StarLiteIdle" }]);
+  }
+  return { manifest, files };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  prepareModel,
+  readPreparedBundle,
+  readPreparedBundleSync
+});

package/dist/prepare.d.ts

@@ -0,0 +1,42 @@
+export interface AssetRecord {
+    file: string;
+    sha256: string;
+    bytes: number;
+}
+export interface VrmManifest {
+    schemaVersion: 1;
+    tool: "vrm-companion-assets";
+    backend: "vrm";
+    model: AssetRecord & {
+        sourceSha256: string;
+    };
+    animations: (AssetRecord & {
+        name: string;
+        durationMs: number;
+    })[];
+    profile?: AssetRecord;
+    publication: {
+        allowRedistribution: boolean;
+    };
+}
+export interface PrepareRequest {
+    model: string;
+    animations?: {
+        name: string;
+        path: string;
+    }[];
+    profile?: string;
+    output: string;
+    allowRedistribution?: boolean;
+}
+/** Validate every source before creating output. Never overwrite an existing bundle. */
+export declare function prepareModel(request: PrepareRequest): Promise<VrmManifest>;
+/** Read only declared, hashed files contained in the prepared bundle. */
+export declare function readPreparedBundle(directory: string): Promise<{
+    manifest: VrmManifest;
+    files: Map<string, Buffer>;
+}>;
+export declare function readPreparedBundleSync(directory: string): {
+    manifest: VrmManifest;
+    files: Map<string, Buffer>;
+};