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

package/BUNDLED_MOTIONS.json

@@ -0,0 +1,63 @@
+{
+  "date": "2026-11-03",
+  "sourceCandidateSha256": "f9efaedaa9aaaa7f6704001d5760928371fbeb23fd170db33c7b731f258a3cd2",
+  "scope": "Humanoid upper-body rotations and optional standard happy/blink only. No meshes, skins, textures, custom model expressions, markers, eye bones, root translations or leg motions.",
+  "authorship": {
+    "CuriousPeek": "Authored by StarCried for StarLite.",
+    "SleepyStartle": "Authored by StarCried for StarLite.",
+    "HappyWave": "Adapted from the existing authored Weiguang RaisedHandWave / Desktop_Approval (Warudo AGIA_Other_wave_arm_01); preserves its complete 3.8-second upper-body performance and standard happy expression, with 0.4-second program-Idle entry/exit. Source is not claimed as original."
+  },
+  "sourceMotionSha256": "f0adbaa2ac42aa7c8c82aa523f2fa5faf82a3e36569efccf0ede9da119b7f9a2",
+  "clips": [
+    {
+      "name": "StarLiteCuriousPeek",
+      "duration": 2.0999999046325684,
+      "bytes": 17380,
+      "sha256": "881238f9c0d6f6d3f0cfabe2d1a02374b60109449f0a0e426242bfd3b2156ee0",
+      "bodyTracks": 43,
+      "expressions": [],
+      "maximumRoundtripError": 3.3306690738754696e-16,
+      "officialLoaderValidated": true
+    },
+    {
+      "name": "StarLiteHappyWave",
+      "duration": 4.6,
+      "bytes": 109148,
+      "sha256": "b57e8858bcf44f7b869dde7477e69093dc3a5fdb4c4bb1c0031b894dbb3612fa",
+      "bodyTracks": 42,
+      "expressions": [
+        "happy"
+      ],
+      "maximumRoundtripError": 0,
+      "officialLoaderValidated": true,
+      "sourceMotion": {
+        "file": "blog/motions/RaisedHandWave.vrma",
+        "name": "RaisedHandWave / authored Desktop_Approval",
+        "sha256": "f0adbaa2ac42aa7c8c82aa523f2fa5faf82a3e36569efccf0ede9da119b7f9a2",
+        "duration": 3.8
+      },
+      "baseline": {
+        "name": "StarLiteIdle",
+        "sha256": "7bd5ce630f5f624c274ad2de026ad5365297c353d7f265654ed97656a738d248",
+        "sampleTime": 0
+      },
+      "timing": {
+        "enterSeconds": 0.4,
+        "sourceSeconds": 3.8,
+        "exitSeconds": 0.4
+      }
+    },
+    {
+      "name": "StarLiteSleepyStartle",
+      "duration": 5.5,
+      "bytes": 35064,
+      "sha256": "d3e9d2583458cc2d63364d44f4b3642bbf7272733c60371933e3a2d2d89910c1",
+      "bodyTracks": 43,
+      "expressions": [
+        "blink"
+      ],
+      "maximumRoundtripError": 4.440892098500626e-16,
+      "officialLoaderValidated": true
+    }
+  ]
+}

package/BUNDLED_MOTIONS.md

@@ -0,0 +1,41 @@
+# Bundled motion provenance
+
+StarLite includes four model-independent humanoid motions. No character mesh,
+texture, skin, private Blender project or proprietary expression is included.
+
+| Runtime name | Duration | Source |
+| --- | --- | --- |
+| StarLiteIdle | 6 s | See [DEFAULT_IDLE.md](DEFAULT_IDLE.md). |
+| StarLiteCuriousPeek | 2.1 s | Authored by StarCried for StarLite. |
+| StarLiteHappyWave | 4.6 s | The authored Weiguang RaisedHandWave, based on Warudo `AGIA_Other_wave_arm_01`, with its standard happy expression. |
+| StarLiteSleepyStartle | 5.5 s | Authored by StarCried for StarLite; optional standard blink. |
+
+The user approved redistribution of selected source motions on 2026-10-10 and
+bundling these three gestures for all imported humanoids on 2026-10-31. This
+records that distribution confirmation, not a claim that Warudo's whole library
+is freely redistributable or that HappyWave is entirely original. Character
+licenses do not apply to or confer rights over the source motion library.
+
+`BUNDLED_MOTIONS.json` records source and final clip hashes. The gesture data
+is losslessly deflated inside the runtime, without fetching external files.
+Run `node tools/embed-builtin-motions.mjs <reviewed VRMA directory>` to regenerate
+the embedded data from files matching those hashes. Tests inflate each clip,
+verify hashes, reject artwork/custom expression channels, and retarget through
+the official loader on synthetic VRM 0 and VRM 1 humanoids.
+
+Only upper-body/finger rotations are animated; hips, legs, eye bones and root
+translations are not overridden. SleepyStartle uses the standard optional blink
+expression; HappyWave uses optional standard happy. Missing optional fingers
+or expression bindings do not prevent body animation playback.
+HappyWave retains the existing authored 3.8 s RaisedHandWave performance and
+happy curve, including secondary motion on the non-waving side. It does not
+reconstruct the raw 0.6 s library loop. A 0.4 s entry and 0.4 s exit connect its
+raised-arm pose to the program StarLiteIdle reference; no constant clearance
+offset changes the active hand arc. Standard happy uses the target model's
+own expression binding, so its facial appearance varies between models.
+Runtime pose calibration follows the selected Idle without
+rewriting model-authored or external clips. Model-specific clipping can still
+require pose or motion adjustments.
+
+Gestures are optional mappings. Adding them never changes an existing user's
+state, click or ambient action selection.

package/README.en.md

@@ -0,0 +1,65 @@
+# @starcried/starlite-vrm
+
+[简体中文](README.md) · English
+
+StarLite's WebGL2 backend for VRM 0/1, embedded glTF animations, external VRMA, limited pointer following, blink, and shared dialogue. The browser entry bundles Three.js, three-vrm, and three-vrm-animation.
+
+```sh
+npm install @starcried/starlite-vrm
+```
+
+## Mount
+
+Provide `<div id="starlite"></div>` and use a bundler:
+
+```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",
+  locale: "en",
+  model: "/model.vrm",
+  fallback: "/portrait.png",
+  dialogue: { click: { lines: ["Hello!", "I'm here."] } },
+  interactions: { pointer: true },
+  render: { fps: 30, maxDevicePixelRatio: 1.5 },
+});
+```
+
+No motion file is required. The runtime uses an authored `Idle` when available, otherwise `StarLiteIdle` supplies a relaxed stance and breathing. Version 0.1.0 also provides optional `StarLiteCuriousPeek`, `StarLiteHappyWave`, and `StarLiteSleepyStartle` gestures for humanoid models. These are reserved names, not character artwork. Assign gestures explicitly; preserve motion provenance in the package notices.
+
+Use `animations: [{name: "Wave", url: "/Wave.vrma"}]` for your own VRMA. `ambient` chooses a baseline loop; `neutralAnimation` chooses the stopped pose. An empty ambient list stops baseline playback. Blink needs effective standard Blink bindings or a full left/right pair; absence disables blink only. Eye following needs valid VRM lookAt. Models must be self-contained.
+
+`inspectVrm(bytes).animations` lists embedded motion names and durations. Pass names in `embeddedAnimations` to reference them from configuration. `getAnimations()` lists loaded embedded, external, and built-in motions. Names must be unique and case-sensitive. Data-only character configuration can be embedded as `extras.starlite.profile`.
+
+Call `destroy()` when unmounting. Hidden models stop animation and physics; resume does not catch up hidden time. A bubble scene may omit animation entirely. `linesByAnimation` must match its selected pool.
+
+## Live adjustments and diagnostics
+
+```js
+controller.setModelAdjustments({
+  idle: { armLiftDegrees: 10, palmTwistDegrees: 5, wristLiftDegrees: 8, handCurl: 0.2, elbowBendDegrees: 8 },
+  gaze: { headStrength: 0.8, eyeStrength: 1, smoothingMs: 120 },
+});
+```
+
+This replaces current adjustments; `{}` restores originals without reloading or restarting motion. Pose parameters calibrate `StarLiteIdle`; the three program gestures begin and end in the selected Idle reference pose, including calibrated arms, wrists and hands. An authored Idle can also supply that reference without itself being modified. Body/upper-arm relative motion is retained. Animated forearms and fingers align smoothly only at entry/exit and keep their authored active shapes, avoiding excessive elbow bending or doubled finger curl. Model-authored and external motions remain unchanged. Upper-arm lift: −30–45°; palm twist and wrist lift: −45–45°; elbow correction: −20–45°; hand curl: 0–1, omitted to keep authored fingers. Head/eye strength is 0–2; smoothing is 20–1000 ms. Missing mappings cannot be created by sliders.
+
+`performance: {show: true}` or `setPerformanceVisible(true)` enables local FPS and timing diagnostics. CPU-side frame cost is not measured GPU execution or CPU utilization. Node's `@starcried/starlite-vrm/inspect` returns capabilities and logical metrics; errors expose controlled codes without private paths or external URIs.
+
+[Configuration](https://github.com/StarCried/starlite/blob/main/docs/configuration.en.md) · [Hexo adapter](https://github.com/StarCried/starlite/blob/main/packages/hexo/README.en.md) · [Shared API](https://github.com/StarCried/starlite/blob/main/packages/core/README.en.md)
+
+Allow appropriate `img-src blob:` and `connect-src blob:` for embedded textures in CSP. To avoid downloading JavaScript on mobile, gate a dynamic import before loading runtime; the static import above does not do that.
+
+Program code: BSD-2-Clause. Models and motion sources retain their own licenses.
+
+### Environment fill light
+
+Optional `environmentLighting: { color: "#b7cfff", strength: 1 }` adds environmental colour using the existing lights. Use six-digit RGB and strength 0–2 (default 1, or 100%). The ordinary range is 0–100%; 100–200% exaggerates colour and brightness response. Part of the side-key energy moves into the ambient fill; the key remains white, model materials/textures stay unchanged, and no lights are added.
+
+At 100% strength, inferred brightness targets are 80% for black, approximately 100% for middle grey and 110% for white. Optional `brightness: 0.95` explicitly sets a target in 0.8–1.1. Strength controls colour and brightness together: at 20%, the effective light multiplier is approximately 90.24%–104.88%; at 200%, it expands to 60%–120%. These bounds describe light energy, not each material's screen-pixel brightness. Chroma is luminance-normalized to avoid double darkening, and near-black colour noise is suppressed.
+
+`controller.setEnvironmentLighting(...)` smoothly updates colours and both light intensities together. `null` or strength 0 restores the original lighting. While paused, a change redraws the still pose without advancing animation. Omitting the option keeps the original lighting; the runtime never captures the screen, and the host supplies the colour.

package/README.md

@@ -1,11 +1,13 @@
 # @starcried/starlite-vrm
 
+简体中文 · [English](README.en.md)
+
 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
+npm install @starcried/starlite-vrm
 ```
 
 ## 挂载
@@ -29,9 +31,9 @@ const controller = await mountModelWidget(host, {
 });
 ```
 
-上例不需要另备动作文件。运行时自动使用模型名为 `Idle` 的动作，否则采用程序唯一内置的 `StarLiteIdle`（基础站姿与轻呼吸）。可通过 `animations: [{name: "Wave", url: "/Wave.vrma"}]` 添加自己的外部动作，或用 `ambient` 和 `neutralAnimation` 指定基础循环与站姿。不附带模型或其他动作库。显式 `ambient: {animations: []}` 可停用基础循环。眨眼为可选能力：需要有效的标准 Blink 表达，或完整的左右 Blink 表达；缺少时模型仍可使用，只停用自动眨眼。眼球跟随需要正确的 VRM lookAt 映射。模型必须自包含，不接受外部纹理或 buffer 引用。
+上例不需要另备动作文件。运行时自动使用模型名为 `Idle` 的动作，否则采用程序内置的 `StarLiteIdle`（基础站姿与轻呼吸）。可通过 `animations: [{name: "Wave", url: "/Wave.vrma"}]` 添加自己的外部动作，或用 `ambient` 和 `neutralAnimation` 指定基础循环与站姿。当前源码还提供 `StarLiteCuriousPeek`、`StarLiteHappyWave`、`StarLiteSleepyStartle` 三个通用人形动作，供所有模型按需映射；不附带模型素材，动作来源保留独立说明。显式 `ambient: {animations: []}` 可停用基础循环。眨眼为可选能力：需要有效的标准 Blink 表达，或完整的左右 Blink 表达；缺少时模型仍可使用，只停用自动眨眼。眼球跟随需要正确的 VRM lookAt 映射。模型必须自包含，不接受外部纹理或 buffer 引用。
 
-`inspectVrm(bytes).animations` 返回模型内嵌动作的名称和时长；将名称列表传入 `embeddedAnimations`，即可在 `ambient`、点击与气泡配置中引用。实际加载后 `getAnimations()` 自动列出内嵌动作和外部 VRMA。未命名动作按顺序显示为 `Animation_1` 等；内嵌动作、外部动作名称不得重复，`StarLiteIdle` 为默认 Idle 保留名。角色配置也可放在模型 JSON 的 `extras.starlite.profile`，内容须符合数据型角色配置规范。
+`inspectVrm(bytes).animations` 返回模型内嵌动作的名称和时长；将名称列表传入 `embeddedAnimations`，即可在 `ambient`、点击与气泡配置中引用。实际加载后 `getAnimations()` 自动列出内嵌动作和外部 VRMA。未命名动作按顺序显示为 `Animation_1` 等；内嵌动作、外部动作名称不得重复，上述四个 `StarLite` 动作名均为保留名。角色配置也可放在模型 JSON 的 `extras.starlite.profile`，内容须符合数据型角色配置规范。
 
 `pause()`／`resume()` 控制更新，`getAnimations()` 列出动作，`playAnimation()`／`stopAnimation()` 控制播放；页面组件卸载时调用 `controller.destroy()` 释放资源。`neutralAnimation` 的首帧作为停止后的基础站姿，避免无角色配置的模型回到 T 姿势。动作名区分大小写；循环在停止或被打断后结束等待。隐藏时停止动画和物理，恢复时不补算离线时间。
 
@@ -39,8 +41,34 @@ const controller = await mountModelWidget(host, {
 
 ## 进阶
 
+`adjustments` 为当前模型提供可选的姿态与跟随校准，例如：
+
+```js
+controller.setModelAdjustments({
+  idle: { armLiftDegrees: 10, palmTwistDegrees: 5, wristLiftDegrees: 8, handCurl: 0.2, elbowBendDegrees: 8 },
+  gaze: { headStrength: 0.8, eyeStrength: 1, smoothingMs: 120 },
+});
+```
+
+相同对象也可作为挂载配置的 `adjustments`。该方法整体替换当前调节，`{}` 恢复原样；实时调节不重新加载模型、不重启动作。双臂抬高范围为 −30～45°，掌心扭转和手腕抬高均为 −45～45°，肘部弯曲为 −20～45°；掌心调节左右对称；手腕抬高在前臂弯曲平面调整手部方向，正值向上折，不移动腕部位置，不改变上臂、前臂或掌心扭转的方向约定。手部张合为 0～1，省略时保留原动作，0 张开、1 握拳，仅处理已映射的标准手指。姿态参数调整程序内置 `StarLiteIdle`；三个程序通用动作以当前选定 Idle 的基础站姿起止，因此会沿用调好的手臂、手腕和手部姿态。也可沿用模型自带 Idle 的站姿，但不会修改该 Idle。通用动作保留身体与上臂的相对运动；有动作的前臂和手指仅在进入、退出时平滑对齐基础姿态，挥手过程中保留原动作的肘部与手型，避免叠加校准后过度弯曲。模型自带动作和外部 VRMA 保持原样。头眼跟随强度各为 0～2，默认 1；0 停用对应跟随，仍尊重现有限角和前景动作方向。平滑时间为 20～1000 ms，省略时沿用 `gaze.smoothingMs`。模型缺少眼球绑定时，调节不能生成眼球跟随。
+
+`0.1.0-alpha.3` 提供 `performance: {show: true}`（默认关闭），也可用
+`controller.setPerformanceVisible?.(true)` 即时切换。含义和测量边界见
+[性能预算](https://github.com/StarCried/starlite/blob/main/docs/performance.md)。
+Node 侧 `@starcried/starlite-vrm/inspect` 返回 `capabilities` 与逻辑 `metrics`；
+`VrmInspectionError.code/details` 提供受控原因及缺失骨骼名，不回显模型路径或外部 URI。
+见[兼容说明](https://github.com/StarCried/starlite/blob/main/docs/model-compatibility.md)。
+
 [动作、句库、相机与性能配置](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；模型和动作由使用者按各自许可提供，微光适配为可选配置。
+
+### 环境补光
+
+可选 `environmentLighting: { color: "#b7cfff", strength: 1 }` 给现有灯光加入环境色；颜色使用六位 RGB，强度范围为 0–2，默认 1（100%）。0–100% 为普通调节范围，100–200% 进一步增强染色和明暗反应。程序会将一部分侧向主光能量分配到环境补光；主光仍为白色，不修改模型材质和贴图，也不增加灯光数量。
+
+默认根据颜色亮度调整总光照：在 100% 强度下，黑色目标为 80%、中灰约 100%、白色 110%。可用 `brightness: 0.95` 显式指定 0.8–1.1 内的目标。强度同时控制颜色与亮度：降低到 20% 时有效光照倍率约为 90.24%–104.88%；提高到 200% 时明暗范围扩大到 60%–120%。这是灯光倍率，不保证所有材质的屏幕像素亮度按同一比例变化。色相经过亮度归一化，避免暗色重复降低亮度；近黑色取色噪声会被抑制。
+
+运行中调用 `controller.setEnvironmentLighting(...)` 同步平滑改变颜色与光强，传 `null` 或强度设为 0 恢复原灯光。暂停时只重绘静止画面，不推进动作。不配置此选项时保持原灯光；运行时不读取屏幕，颜色来源由宿主提供。

package/THIRD_PARTY_NOTICES.md

@@ -10,3 +10,5 @@ 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.
+
+Bundled humanoid gestures have separate recorded provenance; see [BUNDLED_MOTIONS.md](BUNDLED_MOTIONS.md) and `BUNDLED_MOTIONS.json`. They include no model artwork.

package/dist/adjustments.d.ts

@@ -0,0 +1,23 @@
+import { AnimationClip, type Object3D } from "three";
+import type { VRMHumanoid, VRMPose } from "@pixiv/three-vrm";
+import type { ModelAdjustments } from "./types.js";
+type Idle = NonNullable<ModelAdjustments["idle"]>;
+/** A controller-owned derivative of the program Idle; authored clips never enter here. */
+export declare class AdjustableIdle {
+    #private;
+    readonly clip: AnimationClip;
+    constructor(source: AnimationClip, root: Object3D, humanoid: Pick<VRMHumanoid, "getNormalizedBoneNode">, metaVersion?: "0" | "1");
+    update(idle?: Idle): void;
+    /** Refresh stopped/paused neutral without sampling or resetting the live mixer. */
+    neutralPose(pose: VRMPose): VRMPose;
+}
+/** Controller-owned program gestures expressed around the selected neutral pose.
+ * Only generated built-ins enter here; source clips and authored motions stay intact.
+ */
+export declare class RebasedBuiltinGesture {
+    #private;
+    readonly clip: AnimationClip;
+    constructor(source: AnimationClip, root: Object3D, humanoid: Pick<VRMHumanoid, "getNormalizedBoneNode">, pose: VRMPose);
+    update(pose: VRMPose): void;
+}
+export {};

package/dist/adjustments.js

@@ -0,0 +1,201 @@
+import { AnimationClip, MathUtils, PropertyBinding, Quaternion, Vector3 } from "three";
+/** A controller-owned derivative of the program Idle; authored clips never enter here. */
+export class AdjustableIdle {
+    clip;
+    #targets = [];
+    #basis;
+    constructor(source, root, humanoid, metaVersion = "1") {
+        // Match createVRMAnimationClip: VRM0 faces -Z, so its normalized rig's
+        // X/Z rotation axes are the opposite of VRM1's character-space axes.
+        this.#basis = metaVersion === "0" ? -1 : 1;
+        const bones = new Map();
+        for (const [side, sign] of [["left", 1], ["right", -1]]) {
+            const add = (suffix, kind, joint) => {
+                const bone = (side + suffix), node = humanoid.getNormalizedBoneNode(bone);
+                if (node)
+                    bones.set(node, { bone, side: sign, kind, ...(joint ? { joint } : {}) });
+            };
+            add("UpperArm", "arm");
+            add("LowerArm", "elbow");
+            add("Hand", "palm");
+            for (const finger of ["Index", "Middle", "Ring", "Little"]) {
+                for (const joint of ["Proximal", "Intermediate", "Distal"])
+                    add(finger + joint, "finger", joint);
+            }
+            for (const joint of ["Metacarpal", "Proximal", "Distal"])
+                add("Thumb" + joint, "thumb", joint);
+        }
+        const tracks = source.tracks.map(track => {
+            const parsed = PropertyBinding.parseTrackName(track.name);
+            const node = PropertyBinding.findNode(root, parsed.nodeName);
+            const bone = node ? bones.get(node) : undefined;
+            if (!bone || parsed.propertyName !== "quaternion" || track.getValueSize() !== 4 || track.ValueTypeName !== "quaternion")
+                return track;
+            const copy = track.clone();
+            this.#targets.push({ ...bone, source: track, track: copy });
+            return copy;
+        });
+        this.clip = new AnimationClip(source.name, source.duration, tracks, source.blendMode);
+    }
+    update(idle = {}) {
+        const rotation = new Quaternion(), correction = new Quaternion(), wrist = new Quaternion(), motion = new Quaternion(), initial = new Quaternion(), axis = new Vector3();
+        for (const target of this.#targets) {
+            const { source, track, side, kind } = target;
+            track.values.set(source.values);
+            const degrees = kind === "arm" ? idle.armLiftDegrees ?? 0
+                : kind === "palm" ? idle.palmTwistDegrees ?? 0 : kind === "elbow" ? idle.elbowBendDegrees ?? 0 : 0;
+            const hand = kind === "finger" || kind === "thumb";
+            const wristDegrees = kind === "palm" ? idle.wristLiftDegrees ?? 0 : 0;
+            if ((!hand && !degrees && !wristDegrees) || (hand && idle.handCurl === undefined))
+                continue;
+            if (hand) {
+                initial.fromArray(source.values, 0).invert();
+                // The four fingers curl towards the palm. The thumb has its own
+                // opposition and flexion recipe rather than sharing their bend axis.
+                const curl = idle.handCurl;
+                if (kind === "finger") {
+                    const bend = target.joint === "Proximal" ? 70 : target.joint === "Intermediate" ? 90 : 60;
+                    correction.setFromAxisAngle(axis.set(0, 0, -side * this.#basis), MathUtils.degToRad(bend * curl));
+                }
+                else if (target.joint === "Metacarpal") {
+                    correction.setFromAxisAngle(axis.set(0, side, 0), MathUtils.degToRad(35 * curl));
+                    correction.multiply(rotation.setFromAxisAngle(axis.set(0, 0, -side * this.#basis), MathUtils.degToRad(15 * curl)));
+                }
+                else {
+                    correction.setFromAxisAngle(axis.set(0, 0, -side * this.#basis), MathUtils.degToRad((target.joint === "Proximal" ? 45 : 65) * curl));
+                }
+            }
+            else {
+                // A rotation axis is an axial vector: mirroring left/right across X
+                // keeps its X sign and reverses Y/Z. Opposite palm-X signs would
+                // turn one palm inward and the other outward.
+                axis.set(kind === "palm" ? this.#basis : 0, kind === "elbow" ? -side : 0, kind === "arm" ? side * this.#basis : 0);
+                correction.setFromAxisAngle(axis, MathUtils.degToRad(degrees));
+                if (kind === "palm")
+                    wrist.setFromAxisAngle(axis.set(0, 0, side * this.#basis), MathUtils.degToRad(wristDegrees));
+            }
+            for (let at = 0; at < source.values.length; at += 4) {
+                rotation.fromArray(source.values, at);
+                if (hand) {
+                    // Keep the source motion around its first sample, including tiny
+                    // breathing changes, while replacing only the static finger pose.
+                    motion.copy(initial).multiply(rotation);
+                    rotation.copy(correction).multiply(motion);
+                }
+                else if (kind === "palm") {
+                    // Bend in the forearm's frame before applying the palm-local twist,
+                    // so changing palm direction does not rotate the wrist-lift axis.
+                    rotation.premultiply(wrist).multiply(correction);
+                }
+                else if (kind === "arm")
+                    rotation.premultiply(correction);
+                else
+                    rotation.multiply(correction);
+                rotation.normalize().toArray(track.values, at);
+            }
+        }
+    }
+    /** Refresh stopped/paused neutral without sampling or resetting the live mixer. */
+    neutralPose(pose) {
+        const result = { ...pose };
+        for (const { bone, track } of this.#targets) {
+            result[bone] = { ...result[bone], rotation: Array.from(track.values.slice(0, 4)) };
+        }
+        return result;
+    }
+}
+/** Controller-owned program gestures expressed around the selected neutral pose.
+ * Only generated built-ins enter here; source clips and authored motions stay intact.
+ */
+export class RebasedBuiltinGesture {
+    clip;
+    #targets = [];
+    constructor(source, root, humanoid, pose) {
+        const bones = new Map();
+        for (const [name, value] of Object.entries(pose)) {
+            if (!value?.rotation)
+                continue;
+            const bone = name, node = humanoid.getNormalizedBoneNode(bone);
+            if (node)
+                bones.set(node, bone);
+        }
+        const tracks = source.tracks.map(track => {
+            const parsed = PropertyBinding.parseTrackName(track.name);
+            const node = PropertyBinding.findNode(root, parsed.nodeName);
+            const bone = node ? bones.get(node) : undefined;
+            if (!bone || parsed.propertyName !== "quaternion" || track.getValueSize() !== 4 || track.ValueTypeName !== "quaternion")
+                return track;
+            const first = new Quaternion().fromArray(track.values, 0).normalize(), sample = new Quaternion();
+            let boundaryOnly = false;
+            if (/LowerArm|Thumb|Index|Middle|Ring|Little/.test(bone))
+                for (let at = 4; at < track.values.length; at += 4) {
+                    if (first.angleTo(sample.fromArray(track.values, at).normalize()) > 1e-4) {
+                        boundaryOnly = true;
+                        break;
+                    }
+                }
+            const original = track;
+            const base = boundaryOnly ? sampleGestureBoundaries(original, source.duration) : original;
+            const copy = base.clone();
+            this.#targets.push({ bone, source: base, track: copy, boundaryOnly });
+            return copy;
+        });
+        this.clip = new AnimationClip(source.name, source.duration, tracks, source.blendMode);
+        this.update(pose);
+    }
+    update(pose) {
+        const correction = new Quaternion(), first = new Quaternion(), sample = new Quaternion(), boundaryCorrection = new Quaternion();
+        const ramp = Math.min(.4, this.clip.duration / 2);
+        for (const { bone, source, track, boundaryOnly } of this.#targets) {
+            track.values.set(source.values);
+            const target = pose[bone]?.rotation;
+            if (!target)
+                continue;
+            correction.fromArray(target).normalize().multiply(first.fromArray(source.values, 0).normalize().invert());
+            for (let at = 0; at < source.values.length; at += 4) {
+                // q(t) = targetIdle * inverse(originalFirst) * originalSample(t).
+                // Rebuild from immutable source each time, retaining local motion and
+                // mixer-owned sample arrays rather than accumulating calibration.
+                let offset = correction;
+                if (boundaryOnly && ramp > 0) {
+                    // Full offsets can overfold an authored elbow or double a fist's
+                    // curl. Match rest at the boundaries, retaining active elbow/finger
+                    // shapes. Static tracks continue to follow the adjusted rest.
+                    const time = source.times[at / 4];
+                    const t = MathUtils.clamp(Math.min(time, this.clip.duration - time) / ramp, 0, 1);
+                    const weight = 1 - t * t * (3 - 2 * t);
+                    if (weight === 0)
+                        continue;
+                    offset = boundaryCorrection.identity().slerp(correction, weight);
+                }
+                sample.fromArray(source.values, at).premultiply(offset).normalize().toArray(track.values, at);
+            }
+        }
+    }
+}
+/** Sparse authored first/last keys would otherwise linearize the eased offset.
+ * Add at most 50 samples per affected track, only in the bounded two ramps.
+ */
+function sampleGestureBoundaries(source, duration) {
+    const ramp = Math.min(.4, duration / 2);
+    if (ramp <= 0)
+        return source;
+    const times = new Set(source.times);
+    const steps = Math.ceil(ramp * 60);
+    for (let step = 0; step <= steps; step++) {
+        const time = Math.min(ramp, step / 60);
+        times.add(Math.fround(time));
+        times.add(Math.fround(duration - time));
+    }
+    const base = source.clone();
+    base.times = new Float32Array([...times].sort((a, b) => a - b));
+    base.values = new Float32Array(base.times.length * 4);
+    const interpolant = source.createInterpolant(new Float32Array(4));
+    // Preserve every original timestamp/value exactly, including interior keys.
+    const originals = new Map(Array.from(source.times, (time, index) => [time, index]));
+    for (let index = 0; index < base.times.length; index++) {
+        const time = base.times[index], original = originals.get(time);
+        base.values.set(original === undefined ? interpolant.evaluate(time) : source.values.subarray(original * 4, original * 4 + 4), index * 4);
+    }
+    return base;
+}

package/dist/builtin-motion-catalog.d.ts

@@ -0,0 +1,16 @@
+/** Program motions are independent of model artwork and need no network request. */
+export declare const BUILTIN_ANIMATIONS: readonly [{
+    readonly name: "StarLiteIdle";
+    readonly durationMs: 6000;
+}, {
+    readonly name: "StarLiteCuriousPeek";
+    readonly durationMs: 2100;
+}, {
+    readonly name: "StarLiteHappyWave";
+    readonly durationMs: 4600;
+}, {
+    readonly name: "StarLiteSleepyStartle";
+    readonly durationMs: 5500;
+}];
+export type BuiltinAnimationName = (typeof BUILTIN_ANIMATIONS)[number]["name"];
+export declare function isBuiltinAnimation(name: string): name is BuiltinAnimationName;

package/dist/builtin-motion-catalog.js

@@ -0,0 +1,10 @@
+/** Program motions are independent of model artwork and need no network request. */
+export const BUILTIN_ANIMATIONS = [
+    { name: "StarLiteIdle", durationMs: 6000 },
+    { name: "StarLiteCuriousPeek", durationMs: 2100 },
+    { name: "StarLiteHappyWave", durationMs: 4600 },
+    { name: "StarLiteSleepyStartle", durationMs: 5500 },
+];
+export function isBuiltinAnimation(name) {
+    return BUILTIN_ANIMATIONS.some(animation => animation.name === name);
+}