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

package/DEFAULT_IDLE.md

@@ -0,0 +1,21 @@
+# Default Idle provenance
+
+The runtime embeds the currently approved Weiguang relaxed standing and
+breathing motion as StarLiteIdle for humanoid VRM onboarding. It is encoded in
+default-idle-data.ts and decoded locally; no model artwork or additional
+animation download is required.
+
+- Source: DesktopPet/desktop/motions/Idle.vrma in the author's local model project.
+- SHA-256: 7bd5ce630f5f624c274ad2de026ad5365297c353d7f265654ed97656a738d248.
+- Duration: 6 seconds.
+- StarCried authored the relaxed pose and final manual editing/bake. The
+  recorded breathing layer originates from Warudo's Human@SM Breathe; this
+  asset must not be described as entirely original.
+- The user explicitly confirmed redistribution of the selected motions,
+  including this breathing layer, on 2026-10-10 and approved bundling the
+  current Idle for model-only onboarding on 2026-10-14.
+
+This file records provenance and the user's distribution confirmation; it
+does not claim that Warudo's full motion library permits redistribution.
+The model artwork and the other selected motions are not included in this
+program asset.

package/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, StarCried
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @starcried/starlite-vrm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+StarLite 的 WebGL2 VRM 0／1 后端，支持模型内嵌 glTF 动作、外部 VRMA、限角光标跟随、眨眼和公共气泡。浏览器入口已打包 Three.js、three-vrm 和 three-vrm-animation。
+
+在 Node.js 22.12+ 项目中安装 alpha 版本：
+
+```sh
+npm install @starcried/starlite-vrm@alpha
+```
+
+## 挂载
+
+页面提供 `<div id="starlite"></div>`，在使用打包工具的网页项目中：
+
+```js
+import { mountModelWidget } from "@starcried/starlite-vrm";
+import "@starcried/starlite-vrm/widget.css";
+
+const host = document.querySelector("#starlite");
+if (!host) throw new Error("Missing StarLite host");
+
+const controller = await mountModelWidget(host, {
+  backend: "vrm",
+  model: "/model.vrm",
+  fallback: "/portrait.png",
+  dialogue: { click: { lines: ["你好。", "我在这里。"] } },
+  interactions: { pointer: true },
+  render: { fps: 30, maxDevicePixelRatio: 1.5 },
+});
+```
+
+上例不需要另备动作文件。运行时自动使用模型名为 `Idle` 的动作，否则采用程序唯一内置的 `StarLiteIdle`（基础站姿与轻呼吸）。可通过 `animations: [{name: "Wave", url: "/Wave.vrma"}]` 添加自己的外部动作，或用 `ambient` 和 `neutralAnimation` 指定基础循环与站姿。不附带模型或其他动作库。显式 `ambient: {animations: []}` 可停用基础循环。眨眼需要有效的标准 Blink 表达，眼球跟随需要正确的 VRM lookAt 映射。模型必须自包含，不接受外部纹理或 buffer 引用。
+
+`inspectVrm(bytes).animations` 返回模型内嵌动作的名称和时长；将名称列表传入 `embeddedAnimations`，即可在 `ambient`、点击与气泡配置中引用。实际加载后 `getAnimations()` 自动列出内嵌动作和外部 VRMA。未命名动作按顺序显示为 `Animation_1` 等；内嵌动作、外部动作名称不得重复，`StarLiteIdle` 为默认 Idle 保留名。角色配置也可放在模型 JSON 的 `extras.starlite.profile`，内容须符合数据型角色配置规范。
+
+`pause()`／`resume()` 控制更新，`getAnimations()` 列出动作，`playAnimation()`／`stopAnimation()` 控制播放；页面组件卸载时调用 `controller.destroy()` 释放资源。`neutralAnimation` 的首帧作为停止后的基础站姿，避免无角色配置的模型回到 T 姿势。动作名区分大小写；循环在停止或被打断后结束等待。隐藏时停止动画和物理，恢复时不补算离线时间。
+
+气泡可以独立使用，例如 `dialogue: {click: {lines: ["你好。"]}}`；需要动作时再添加 `animation` 或 `animations`。`linesByAnimation` 仍须完整对应动作池。
+
+## 进阶
+
+[动作、句库、相机与性能配置](https://github.com/StarCried/starlite/blob/main/docs/configuration.md) · [构建博客资源](https://github.com/StarCried/starlite/blob/main/docs/examples/prepare-vrm.cjs) · [Hexo 插件](https://github.com/StarCried/starlite/blob/main/packages/hexo/README.md) · [开发与验证](https://github.com/StarCried/starlite/blob/main/docs/development.md)
+
+配置 CSP 的网站须为模型内嵌贴图允许适用的 `img-src blob:` 和 `connect-src blob:`。独立网页若要在手机上避免加载运行时，须在检查屏宽后动态导入；上例的静态导入会下载 JS。
+
+BSD-2-Clause；模型和动作由使用者按各自许可提供，微光适配为可选配置。

package/THIRD_PARTY_LICENSES.txt

@@ -0,0 +1,80 @@
+THIRD-PARTY LICENSES FOR @starcried/starlite-vrm
+
+This file is generated from the exact locked dependency sources.
+Regenerate it with `npm run licenses:generate`.
+
+COMPONENT INVENTORY
+
+- @pixiv/three-vrm 3.5.5 | MIT | https://github.com/pixiv/three-vrm.git
+- @pixiv/three-vrm-animation 3.5.5 | MIT | https://github.com/pixiv/three-vrm.git
+- @pixiv/three-vrm-core 3.5.5 | MIT | https://github.com/pixiv/three-vrm.git
+- @pixiv/three-vrm-materials-hdr-emissive-multiplier 3.5.5 | MIT | https://github.com/pixiv/three-vrm.git
+- @pixiv/three-vrm-materials-mtoon 3.5.5 | MIT | https://github.com/pixiv/three-vrm.git
+- @pixiv/three-vrm-materials-v0compat 3.5.5 | MIT | https://github.com/pixiv/three-vrm.git
+- @pixiv/three-vrm-node-constraint 3.5.5 | MIT | https://github.com/pixiv/three-vrm.git
+- @pixiv/three-vrm-springbone 3.5.5 | MIT | https://github.com/pixiv/three-vrm.git
+- three 0.186.0 | MIT | https://github.com/mrdoob/three.js
+
+LICENSE AND NOTICE TEXTS
+
+================================================================================
+SHA-256: 279ec82987aec7e72ecb9850bb704a87e352d577bc7581454c30f3551a88ea92
+Applies to:
+- @pixiv/three-vrm 3.5.5 (LICENSE)
+- @pixiv/three-vrm-animation 3.5.5 (LICENSE)
+- @pixiv/three-vrm-core 3.5.5 (LICENSE)
+- @pixiv/three-vrm-materials-hdr-emissive-multiplier 3.5.5 (LICENSE)
+- @pixiv/three-vrm-materials-mtoon 3.5.5 (LICENSE)
+- @pixiv/three-vrm-materials-v0compat 3.5.5 (LICENSE)
+- @pixiv/three-vrm-node-constraint 3.5.5 (LICENSE)
+- @pixiv/three-vrm-springbone 3.5.5 (LICENSE)
+
+Copyright (c) 2019-2026 pixiv Inc.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+================================================================================
+SHA-256: 8b378ebe60e2fe500158cb0ac71cb5e8b7d92953c2abcc63a0eb90499653b5bc
+Applies to:
+- three 0.186.0 (LICENSE)
+
+The MIT License
+
+Copyright © 2010-2026 three.js authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,12 @@
+# Third-party notices
+
+The browser bundle includes Three.js and Pixiv three-vrm (including its VRM
+animation, MToon, constraints and spring-bone packages), distributed under MIT.
+Exact versions and license texts are in THIRD_PARTY_LICENSES.txt.
+
+No third-party desktop-pet code or character model artwork is included.
+The bundled StarLiteIdle contains the approved relaxed pose and a breathing
+layer originating from Warudo's Human@SM Breathe. Its hash, authorship and the
+user's redistribution confirmation are recorded in DEFAULT_IDLE.md; it is
+not represented as a wholly original or separately MIT-licensed motion.
+Other model and motion rights remain the responsibility of their owner.

package/dist/camera.d.ts

@@ -0,0 +1,17 @@
+import { Box3, PerspectiveCamera, Vector3, type Object3D } from "three";
+import type { ModelViewport, VrmWidgetConfig } from "./types.js";
+/** Measure the visible, posed mesh once. Hidden accessories and stale skin bounds
+ * must not widen the portrait, and a later resize must not chase a moving hand. */
+export declare function visibleModelBounds(root: Object3D): Box3;
+export declare function framePortrait(camera: PerspectiveCamera, bounds: Box3, aspect: number, render: VrmWidgetConfig["render"], options: VrmWidgetConfig["camera"], anchor?: Vector3): Vector3;
+/** Expand the transparent surface around a fixed logical portrait. Padding is
+ * quantized and retained until destroy, so an Idle return never rescales or
+ * moves the character and small spring movements do not resize every frame. */
+export declare class ExpandedViewport {
+    #private;
+    constructor(padding?: NonNullable<VrmWidgetConfig["render"]>["viewportPadding"]);
+    get rect(): ModelViewport;
+    resize(width: number, height: number): boolean;
+    expand(camera: PerspectiveCamera, bounds: Box3): boolean;
+    apply(camera: PerspectiveCamera): void;
+}

package/dist/camera.js

@@ -0,0 +1,112 @@
+import { Box3, MathUtils, Mesh, PerspectiveCamera, Vector3 } from "three";
+/** Measure the visible, posed mesh once. Hidden accessories and stale skin bounds
+ * must not widen the portrait, and a later resize must not chase a moving hand. */
+export function visibleModelBounds(root) {
+    root.updateMatrixWorld(true);
+    const bounds = new Box3(), point = new Vector3();
+    root.traverseVisible(object => {
+        if (!(object instanceof Mesh))
+            return;
+        const mesh = object;
+        mesh.skeleton?.update();
+        const positions = mesh.geometry.getAttribute("position");
+        if (!positions)
+            return;
+        for (let i = 0; i < positions.count; i++)
+            bounds.expandByPoint(mesh.getVertexPosition(i, point).applyMatrix4(mesh.matrixWorld));
+    });
+    const size = bounds.getSize(new Vector3()), center = bounds.getCenter(new Vector3());
+    if (![...size, ...center].every(Number.isFinite) || size.length() === 0)
+        throw new Error("invalid model bounds");
+    return bounds;
+}
+export function framePortrait(camera, bounds, aspect, render, options, anchor) {
+    const size = bounds.getSize(new Vector3()), target = bounds.getCenter(new Vector3());
+    target.y = bounds.min.y + size.y * (options?.targetHeight ?? .5);
+    if (anchor)
+        target.copy(anchor);
+    camera.fov = options?.fovDegrees ?? 30;
+    camera.aspect = aspect;
+    const yaw = MathUtils.degToRad(options?.yawDegrees ?? 0), pitch = MathUtils.degToRad(options?.pitchDegrees ?? 0);
+    const normal = new Vector3(Math.sin(yaw) * Math.cos(pitch), Math.sin(pitch), Math.cos(yaw) * Math.cos(pitch));
+    const right = new Vector3().crossVectors(camera.up, normal).normalize(), up = new Vector3().crossVectors(normal, right).normalize();
+    const tan = Math.tan(MathUtils.degToRad(camera.fov / 2)) * (render?.fitPadding ?? .9);
+    let distance = 0;
+    for (const x of [bounds.min.x, bounds.max.x])
+        for (const y of [bounds.min.y, bounds.max.y])
+            for (const z of [bounds.min.z, bounds.max.z]) {
+                const offset = new Vector3(x, y, z).sub(target);
+                distance = Math.max(distance, offset.dot(normal) + Math.max(Math.abs(offset.dot(right)) / (tan * aspect), Math.abs(offset.dot(up)) / tan));
+            }
+    camera.position.copy(target).addScaledVector(normal, distance / (render?.initialScale ?? 1));
+    camera.lookAt(target);
+    camera.updateProjectionMatrix();
+    camera.updateMatrixWorld(true);
+    return target;
+}
+/** Expand the transparent surface around a fixed logical portrait. Padding is
+ * quantized and retained until destroy, so an Idle return never rescales or
+ * moves the character and small spring movements do not resize every frame. */
+export class ExpandedViewport {
+    #width = 0;
+    #height = 0;
+    #left = 0;
+    #top = 0;
+    #right = 0;
+    #bottom = 0;
+    #point = new Vector3();
+    #fixed;
+    constructor(padding) {
+        this.#fixed = padding !== undefined;
+        if (padding) {
+            this.#left = padding.left;
+            this.#top = padding.top;
+            this.#right = padding.right;
+            this.#bottom = padding.bottom;
+        }
+    }
+    get rect() {
+        return { left: 0 - this.#left, top: 0 - this.#top, width: this.#width + this.#left + this.#right,
+            height: this.#height + this.#top + this.#bottom, baseWidth: this.#width, baseHeight: this.#height };
+    }
+    resize(width, height) {
+        if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0)
+            throw new Error("invalid portrait viewport");
+        if (width === this.#width && height === this.#height)
+            return false;
+        this.#width = width;
+        this.#height = height;
+        return true;
+    }
+    expand(camera, bounds) {
+        if (this.#fixed || bounds.isEmpty())
+            return false;
+        let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+        for (const x of [bounds.min.x, bounds.max.x])
+            for (const y of [bounds.min.y, bounds.max.y])
+                for (const z of [bounds.min.z, bounds.max.z]) {
+                    const p = this.#point.set(x, y, z).project(camera);
+                    const px = (p.x + 1) * this.#width / 2, py = (1 - p.y) * this.#height / 2;
+                    if (![px, py].every(Number.isFinite))
+                        throw new Error("non-finite portrait projection");
+                    minX = Math.min(minX, px);
+                    minY = Math.min(minY, py);
+                    maxX = Math.max(maxX, px);
+                    maxY = Math.max(maxY, py);
+                }
+        const grow = (current, required) => Math.max(current, Math.ceil(required / 32) * 32);
+        const left = grow(this.#left, 8 - minX), top = grow(this.#top, 8 - minY);
+        const right = grow(this.#right, maxX + 8 - this.#width), bottom = grow(this.#bottom, maxY + 8 - this.#height);
+        if (left === this.#left && top === this.#top && right === this.#right && bottom === this.#bottom)
+            return false;
+        this.#left = left;
+        this.#top = top;
+        this.#right = right;
+        this.#bottom = bottom;
+        return true;
+    }
+    apply(camera) {
+        const rect = this.rect;
+        camera.setViewOffset(this.#width, this.#height, rect.left, rect.top, rect.width, rect.height);
+    }
+}

package/dist/character.d.ts

@@ -0,0 +1,10 @@
+import type { VRM } from "@pixiv/three-vrm";
+import type { CharacterProfile } from "./types.js";
+export declare function sampleCurve(curve: readonly (readonly [number, number])[], time: number): number;
+export declare class CharacterBehavior {
+    #private;
+    constructor(vrm: VRM, profile?: CharacterProfile);
+    beforeExpressions(delta: number, authoredBlink?: boolean): void;
+    afterExpressions(): void;
+    reset(): void;
+}

package/dist/character.js

@@ -0,0 +1,134 @@
+import { Quaternion, Vector3 } from "three";
+export function sampleCurve(curve, time) {
+    for (let i = 1; i < curve.length; i++) {
+        const a = curve[i - 1], b = curve[i];
+        if (time <= b[0])
+            return a[1] + (b[1] - a[1]) * Math.max(0, (time - a[0]) / (b[0] - a[0]));
+    }
+    return curve.at(-1)?.[1] ?? 0;
+}
+export class CharacterBehavior {
+    #vrm;
+    #profile;
+    #morphs = new Map();
+    #earBones = new Map();
+    #baseEar = new Map();
+    #time = 0;
+    #weights = "";
+    #blinkAmount = 0;
+    #authoredBlink;
+    constructor(vrm, profile) {
+        this.#vrm = vrm;
+        this.#profile = profile;
+        if (!profile)
+            return;
+        vrm.scene.traverse((object) => {
+            const mesh = object;
+            for (const [name, index] of Object.entries(mesh.morphTargetDictionary ?? {})) {
+                const targets = this.#morphs.get(name) ?? [];
+                targets.push({ mesh, index });
+                this.#morphs.set(name, targets);
+            }
+        });
+        for (const name of profile.earBones) {
+            const bone = findAuthoredNode(vrm.scene, name);
+            if (!bone)
+                throw new Error(`character profile is missing bone: ${name}`);
+            this.#earBones.set(name, bone);
+            this.#baseEar.set(name, { rotation: bone.quaternion.clone(), position: bone.position.clone() });
+        }
+        for (const value of Object.values(profile.expressions)) {
+            if (!vrm.expressionManager?.getExpression(value.expression))
+                throw new Error(`character expression is missing: ${value.expression}`);
+            if (value.blink && !this.#morphs.has(value.blink))
+                throw new Error(`character blink morph is missing: ${value.blink}`);
+        }
+        for (const [name, visible] of [[profile.accessories.collar, profile.accessories.collarVisible], [profile.accessories.cone, profile.accessories.coneVisible]]) {
+            const object = findAuthoredNode(vrm.scene, name);
+            if (!object)
+                throw new Error(`character accessory is missing: ${name}`);
+            object.visible = visible;
+        }
+    }
+    beforeExpressions(delta, authoredBlink = false) {
+        this.#time += delta;
+        if (authoredBlink && !this.#profile)
+            return;
+        const manager = this.#vrm.expressionManager;
+        // Recipes without a correction already have closed eyes (e.g. Proud), so
+        // their share also replaces Basis. Additive totals above one stay additive.
+        const total = this.#profile ? Object.values(this.#profile.expressions).reduce((sum, item) => sum + Math.min(1, Math.max(0, manager?.getValue(item.expression) ?? 0)), 0) : 0;
+        // Each custom correction closes its expression's share of the eyelids.
+        // Ordinary blink must still close the remaining Basis share during fades.
+        const curve = this.#profile?.blink.curve ?? [[0, 0], [3.4, 0], [3.48, 1], [3.52, 1], [3.65, 0], [4.7, 0]];
+        this.#authoredBlink = authoredBlink ? manager?.getValue("blink") ?? 0 : undefined;
+        this.#blinkAmount = this.#authoredBlink ?? sampleCurve(curve, this.#time % (this.#profile?.blink.period ?? 4.7));
+        manager?.setValue("blink", Math.max(0, 1 - total) * this.#blinkAmount);
+    }
+    afterExpressions() {
+        const profile = this.#profile;
+        if (!profile)
+            return;
+        const weights = Object.entries(profile.expressions).map(([name, item]) => [name, Math.min(1, Math.max(0, this.#vrm.expressionManager?.getValue(item.expression) ?? 0))]);
+        const key = weights.map(([, weight]) => weight.toFixed(4)).join(",");
+        if (key !== this.#weights) {
+            if (!weights.some(([, weight]) => weight > .001) || !this.#weights)
+                this.#time = 0;
+            this.#weights = key;
+            // Set the authored ear rest pose only when expression weights change;
+            // steady frames leave the spring solver's inertia intact.
+            const total = weights.reduce((sum, [, weight]) => sum + weight, 0);
+            for (const [name, bone] of this.#earBones) {
+                const neutral = profile.earPoses.Neutral?.[name];
+                const base = this.#baseEar.get(name);
+                const reference = neutral ? new Quaternion(...neutral.rotation) : base.rotation;
+                const rotation = reference.clone();
+                let accumulated = Math.max(0, 1 - total);
+                const position = (neutral?.position ? new Vector3(...neutral.position) : base.position.clone()).multiplyScalar(accumulated);
+                for (const [emotion, weight] of weights) {
+                    if (weight <= 0)
+                        continue;
+                    const pose = profile.earPoses[emotion]?.[name];
+                    if (!pose)
+                        throw new Error(`missing ear pose: ${emotion}/${name}`);
+                    rotation.slerp(new Quaternion(...pose.rotation), weight / (accumulated + weight));
+                    position.addScaledVector(pose.position ? new Vector3(...pose.position) : base.position, weight);
+                    accumulated += weight;
+                }
+                bone.quaternion.copy(rotation);
+                bone.position.copy(position.divideScalar(Math.max(1, total)));
+                // Spring joints disable matrixAutoUpdate. Their rest state reads both
+                // quaternion and matrix, so compose the authored local pose before
+                // propagating world matrices or capturing a new spring rest direction.
+                // Otherwise a changing expression mixes the new rotation with the
+                // preceding frame's simulated matrix and makes the ears jump.
+                bone.updateMatrix();
+            }
+            this.#vrm.scene.updateMatrixWorld(true);
+            // Expression changes establish a new authored rest direction for ears only.
+            for (const joint of this.#vrm.springBoneManager?.joints ?? []) {
+                if (profile.earBones.some((name) => this.#earBones.get(name) === joint.bone))
+                    joint.setInitState();
+            }
+        }
+        for (const [name, weight] of weights) {
+            const blink = profile.expressions[name]?.blink;
+            if (!blink)
+                continue;
+            for (const { mesh, index } of this.#morphs.get(blink) ?? [])
+                mesh.morphTargetInfluences[index] = weight * this.#blinkAmount;
+        }
+        // Only the applied neutral share changes; the animation's sampled value
+        // remains available to the next authored frame or captured-pose transition.
+        if (this.#authoredBlink !== undefined)
+            this.#vrm.expressionManager?.setValue("blink", this.#authoredBlink);
+        this.#authoredBlink = undefined;
+    }
+    reset() { this.#time = 0; this.#weights = ""; this.#blinkAmount = 0; this.#authoredBlink = undefined; }
+}
+function findAuthoredNode(root, name) {
+    let found;
+    root.traverse((node) => { if (node.name === name || node.userData.name === name)
+        found = node; });
+    return found;
+}

package/dist/config.cjs

@@ -0,0 +1,152 @@
+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/config.ts
+var config_exports = {};
+__export(config_exports, {
+  validateCharacterProfile: () => validateCharacterProfile,
+  validateVrmWidgetConfig: () => validateVrmWidgetConfig
+});
+module.exports = __toCommonJS(config_exports);
+
+// ../core/dist/dialogue.js
+function resolveDialogueSentences(input, animations, field) {
+  const resolve = (value, path) => {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 128) {
+      throw new Error(`${path} must contain 1..=128 sentences`);
+    }
+    return value.map((line, index) => {
+      if (typeof line !== "string")
+        throw new Error(`${path}[${index}] must be a string`);
+      const text = line.trim();
+      const bytes = new TextEncoder().encode(text).byteLength;
+      if (bytes < 1 || bytes > 1024)
+        throw new Error(`${path}[${index}] must contain 1..=1024 UTF-8 bytes`);
+      return text;
+    });
+  };
+  const lines = input.lines === void 0 ? void 0 : resolve(input.lines, `${field}.lines`);
+  const mapping = input.linesByAnimation;
+  if (mapping === void 0) {
+    if (!lines)
+      throw new Error(`${field}.lines or linesByAnimation is required`);
+    return { lines };
+  }
+  if (!mapping || typeof mapping !== "object" || Array.isArray(mapping)) {
+    throw new Error(`${field}.linesByAnimation must be an animation-to-sentences object`);
+  }
+  if (!animations.length)
+    throw new Error(`${field}.linesByAnimation needs an animation`);
+  const selected = new Set(animations);
+  const keys = Object.keys(mapping);
+  if (keys.length !== selected.size || keys.some((name) => !selected.has(name)) || animations.some((name) => !Object.hasOwn(mapping, name))) {
+    throw new Error(`${field}.linesByAnimation must cover exactly the selected animations`);
+  }
+  const linesByAnimation = Object.fromEntries(keys.map((name) => [name, resolve(mapping[name], `${field}.linesByAnimation[${JSON.stringify(name)}]`)]));
+  return { ...lines ? { lines } : {}, linesByAnimation };
+}
+
+// src/config.ts
+function finite(value, min, max) {
+  return typeof value === "number" && Number.isFinite(value) && value >= min && value <= max;
+}
+function validateVrmWidgetConfig(config) {
+  if (!config || config.backend !== void 0 && config.backend !== "vrm") throw new Error("invalid VRM backend");
+  if (config.interactions?.passThrough !== void 0 && typeof config.interactions.passThrough !== "boolean") throw new Error("interactions.passThrough must be boolean");
+  if (config.interactions?.passThrough && config.interactions.drag) throw new Error("passThrough and drag cannot both be enabled");
+  for (const key of ["model", "fallback"]) if (typeof config[key] !== "string" || !config[key].trim()) throw new Error(`${key} is required`);
+  if (config.render?.fps !== void 0 && config.render.fps !== 30 && config.render.fps !== 60 && config.render.fps !== "display") throw new Error("frame rate must be 30, 60 or display");
+  const checks = [
+    [config.render?.maxDevicePixelRatio ?? 1.5, 1, 1.5],
+    [config.render?.initialScale ?? 1, 0.25, 3],
+    [config.render?.fitPadding ?? 0.9, 0.1, 1],
+    [config.display?.width ?? 320, 1, 4096],
+    [config.display?.height ?? 480, 1, 4096],
+    [config.camera?.yawDegrees ?? 0, -45, 45],
+    [config.camera?.pitchDegrees ?? 0, -20, 20],
+    [config.camera?.fovDegrees ?? 30, 15, 50],
+    [config.camera?.targetHeight ?? 0.5, 0.35, 0.65],
+    [config.gaze?.maxYawDegrees ?? 25, 0, 45],
+    [config.gaze?.maxPitchDegrees ?? 15, 0, 30],
+    [config.gaze?.smoothingMs ?? 100, 20, 1e3],
+    [config.mobile?.breakpoint ?? 768, 1, 4096],
+    [config.network?.requestTimeoutMs ?? 3e4, 100, 12e4],
+    [config.network?.modelMaxBytes ?? 64 * 1024 * 1024, 1, 64 * 1024 * 1024]
+  ];
+  if (checks.some(([value, min, max]) => !finite(value, min, max))) throw new Error("invalid VRM display or network limits");
+  const padding = config.render?.viewportPadding;
+  if (padding !== void 0) {
+    if (!padding || typeof padding !== "object" || Array.isArray(padding) || [padding.left, padding.top, padding.right, padding.bottom].some((value) => !finite(value, 0, 1024)) || (config.display?.width ?? 320) + padding.left + padding.right > 4096 || (config.display?.height ?? 480) + padding.top + padding.bottom > 4096) throw new Error("invalid fixed viewport padding");
+  }
+  const animations = config.animations ?? [];
+  if (!Array.isArray(animations) || animations.length > 64) throw new Error("at most 64 animations are supported");
+  const names = /* @__PURE__ */ new Set();
+  if (config.embeddedAnimations !== void 0 && (!Array.isArray(config.embeddedAnimations) || config.embeddedAnimations.length > 64)) throw new Error("invalid embedded animation catalog");
+  for (const name of config.embeddedAnimations ?? []) {
+    if (typeof name !== "string" || !name.trim() || name.length > 128 || names.has(name)) throw new Error("invalid or duplicate embedded animation");
+    names.add(name);
+  }
+  for (const animation of animations) {
+    if (!animation || typeof animation.name !== "string" || !animation.name.trim() || animation.name.length > 128 || names.has(animation.name) || typeof animation.url !== "string" || !animation.url.trim()) throw new Error("invalid or duplicate animation");
+    if (animation.durationMs !== void 0 && !finite(animation.durationMs, 1, 6e5)) throw new Error("invalid animation duration");
+    names.add(animation.name);
+  }
+  names.add("StarLiteIdle");
+  for (const name of config.ambient?.animations ?? []) if (!names.has(name)) throw new Error(`unknown ambient animation: ${name}`);
+  if ((config.ambient?.animations?.length ?? 0) > 1) throw new Error("VRM supports one explicitly configured ambient clip");
+  if (config.neutralAnimation !== void 0 && !names.has(config.neutralAnimation)) throw new Error("unknown neutral animation");
+  const click = config.interactions?.click;
+  const pool = (value) => Array.isArray(value) && value.length > 0 && value.length <= 20 && new Set(value).size === value.length && value.every((name) => typeof name === "string" && names.has(name));
+  if (click && (click.animations !== void 0 ? !pool(click.animations) : !click.animation || !names.has(click.animation))) throw new Error("Click must name available animations");
+  for (const [name, scene] of Object.entries(config.dialogue ?? {})) {
+    if (!scene) continue;
+    if (scene.animations !== void 0 && !pool(scene.animations)) throw new Error("invalid dialogue animation pool");
+    if (scene.animation !== void 0 && !names.has(scene.animation)) throw new Error("invalid dialogue scene");
+    resolveDialogueSentences(scene, scene.animations ?? (scene.animation ? [scene.animation] : []), `dialogue.${name}`);
+  }
+  if (config.profile && typeof config.profile !== "string") validateCharacterProfile(config.profile);
+}
+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];
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  validateCharacterProfile,
+  validateVrmWidgetConfig
+});

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+import type { CharacterProfile, VrmWidgetConfig } from "./types.js";
+export declare function validateVrmWidgetConfig(config: VrmWidgetConfig): void;
+export declare function validateCharacterProfile(input: unknown): asserts input is CharacterProfile;