@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/poseMode/PosePickerFrame.js

@@ -0,0 +1,164 @@
+// packages/camera-studio/src/poseMode/PosePickerFrame.tsx
+/**
+ * 内置姿势选择框体(2026-10-01):左侧停靠卡片框,与模型选择框体同形态
+ * (视觉常量对齐 AssetLibraryPanel)。这是 PosePickerProps 的参考实现——
+ * 宿主经 pickerRegistry 注册自己的组件后,本框体整体被替换。
+ *
+ * 纯选择语义:第一卡永远「T 姿势」(绑定/默认),往下是同骨架族库预设
+ * (异族置灰);当前值高亮;管理功能(删除/保存姿势)留在资产库姿势页,
+ * 不进本框。选项带 thumbUrl 时整框切两列网格卡(2026-10-05 起手势条目
+ * 挂 QBX 预览图),全无图时维持单列名称行。
+ *
+ * 样式全部 inline:本组件经 createPortal 从 shadow DOM 里的属性编辑器
+ * 挂到 document.body,React 树上的 styled-components 上下文可能指向
+ * shadow 根,样式表不可靠(与姿势弹框同款约束)。
+ *
+ * Esc 分层:容器自己的 onKeyDown 关框并 stopPropagation——焦点在框内时
+ * Esc 只关框,不触发姿势模式退出/其他全局 Esc 语义;焦点在框外时 Esc
+ * 维持既有语义(姿势模式退出等),框不关。
+ */
+import React from 'react';
+import { useI18n } from '@dreamerbird/studio/i18n';
+import { getUiConfig } from '../uiConfig';
+export function PosePickerFrame({ options, current, onPick, onClose, title, }) {
+    const { t } = useI18n();
+    // 任一选项带缩略图 → 两列网格卡(图上文下);全无图 → 维持单列名称行
+    const hasThumbs = options.some((o) => o.thumbUrl);
+    return (React.createElement("div", { "data-testid": "PosePickerFrame", tabIndex: -1, onKeyDown: (e) => {
+            if (e.key === 'Escape') {
+                e.stopPropagation();
+                onClose();
+            }
+        }, style: {
+            position: 'fixed',
+            top: 0,
+            bottom: 0,
+            left: 0,
+            width: 260,
+            // studio 大纲面板的层级是 100,框体必须盖过它;基准可配(ui.zIndexBase)
+            zIndex: getUiConfig().zIndexBase,
+            display: 'flex',
+            flexDirection: 'column',
+            background: 'var(--theatre-panel-bg, #282b2f)',
+            borderRight: '1px solid var(--theatre-panel-border, #1f1f1f)',
+            color: 'var(--theatre-text-primary, #ffffff)',
+            fontSize: 11,
+            fontFamily: 'var(--theatre-font-family, -apple-system, BlinkMacSystemFont, Segoe WPC, Segoe Editor, HelveticaNeue-Light, Ubuntu, Droid Sans, sans-serif)',
+            outline: 'none',
+            userSelect: 'none',
+        } },
+        React.createElement("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 4,
+                padding: '4px 6px 4px 12px',
+                backgroundColor: '#25272b',
+                borderBottom: '1px solid rgb(0 0 0 / 13%)',
+            } },
+            React.createElement("span", { style: {
+                    fontSize: 11,
+                    fontWeight: 600,
+                    color: 'var(--theatre-head-title, #bbbbbb)',
+                } }, title ?? t('pg.pose.selectorTitle')),
+            React.createElement("div", { style: { flex: 1 } }),
+            React.createElement("button", { type: "button", "aria-label": t('pg.pose.selectorClose'), onClick: onClose, style: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    width: 24,
+                    height: 24,
+                    padding: 0,
+                    border: 'none',
+                    borderRadius: 2,
+                    background: 'transparent',
+                    color: 'var(--theatre-text-secondary, #cccccc)',
+                    cursor: 'pointer',
+                    fontSize: 13,
+                    lineHeight: 1,
+                } }, "\u2715")),
+        React.createElement("div", { style: {
+                flex: 1,
+                overflowY: 'auto',
+                padding: 12,
+                ...(hasThumbs
+                    ? {
+                        display: 'flex',
+                        flexWrap: 'wrap',
+                        gap: 8,
+                        alignContent: 'flex-start',
+                    }
+                    : { display: 'flex', flexDirection: 'column', gap: 8 }),
+            } }, options.map((opt) => {
+            const isCurrent = opt.key === current;
+            const border = `1px solid ${isCurrent
+                ? 'rgba(125, 193, 200, 0.45)'
+                : 'var(--theatre-panel-border, #1f1f1f)'}`;
+            if (hasThumbs) {
+                return (React.createElement("div", { key: opt.key, "data-pose-option": opt.key, title: opt.disabled ? opt.hint?.trim() : undefined, onClick: () => {
+                        if (opt.disabled)
+                            return;
+                        onPick(opt.key);
+                    }, style: {
+                        // 两列:50% 减半个 gap;boxSizing 让边框不挤出换行
+                        width: 'calc(50% - 4px)',
+                        boxSizing: 'border-box',
+                        borderRadius: 3,
+                        background: isCurrent
+                            ? 'rgba(125, 193, 200, 0.18)'
+                            : 'rgba(0, 0, 0, 0.18)',
+                        border,
+                        cursor: opt.disabled ? 'default' : 'pointer',
+                        opacity: opt.disabled ? 0.5 : 1,
+                        overflow: 'hidden',
+                    } },
+                    React.createElement("div", { style: {
+                            position: 'relative',
+                            width: '100%',
+                            height: 112,
+                            background: 'rgba(0, 0, 0, 0.25)',
+                        } }, opt.thumbUrl && (React.createElement("img", { src: opt.thumbUrl, alt: "", draggable: false, style: {
+                            position: 'absolute',
+                            inset: 0,
+                            width: '100%',
+                            height: '100%',
+                            objectFit: 'cover',
+                            display: 'block',
+                        } }))),
+                    React.createElement("div", { style: {
+                            padding: '4px 6px',
+                            overflow: 'hidden',
+                            textOverflow: 'ellipsis',
+                            whiteSpace: 'nowrap',
+                            textAlign: 'center',
+                        } },
+                        opt.label,
+                        opt.hint && (React.createElement("span", { style: { color: 'var(--theatre-text-muted, #888888)' } }, opt.hint.trim())))));
+            }
+            return (React.createElement("div", { key: opt.key, "data-pose-option": opt.key, title: opt.disabled ? opt.hint?.trim() : undefined, onClick: () => {
+                    if (opt.disabled)
+                        return;
+                    onPick(opt.key);
+                }, style: {
+                    padding: '10px 12px',
+                    borderRadius: 3,
+                    background: isCurrent
+                        ? 'rgba(125, 193, 200, 0.18)'
+                        : 'rgba(0, 0, 0, 0.18)',
+                    border,
+                    cursor: opt.disabled ? 'default' : 'pointer',
+                    opacity: opt.disabled ? 0.5 : 1,
+                    display: 'flex',
+                    justifyContent: 'space-between',
+                    alignItems: 'center',
+                    gap: 8,
+                    whiteSpace: 'nowrap',
+                    overflow: 'hidden',
+                } },
+                React.createElement("span", { style: { overflow: 'hidden', textOverflow: 'ellipsis' } }, opt.label),
+                opt.hint && (React.createElement("span", { style: {
+                        color: 'var(--theatre-text-muted, #888888)',
+                        flexShrink: 0,
+                    } }, opt.hint.trim()))));
+        }))));
+}
+export default PosePickerFrame;

package/dist/poseMode/PosePropEditor.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 姿势属性编辑器(2026-10-01 属性面板姿势行 + 框体注册制):经 core 的
+ * editor 配置项 + studio 自定义编辑器注册表,替换 pose 属性在详情面板里
+ * 的值区域。
+ *
+ * 行内显示 = poseDisplayText 三态:T 姿势(空值/绑定)/ 预设名称(库)/
+ * 自定义姿势(双击模型进姿势模式摆的,或选预设后又改过)。点值区域开
+ * 左侧停靠的姿势选择框(不再是 select 式弹框):T 姿势 + 同骨架族库
+ * 预设(异族置灰)——框体就是纯姿势列表,自定义不设选项,只能编辑产生。
+ *
+ * 框体注册制:pickerRegistry 的 'pose' 槽位注册了宿主组件就用宿主的
+ * (props = 组装好的 options/current + onPick/onClose 回调),没注册用内置
+ * PosePickerFrame。库管开/关与数据,宿主组件只画 UI、调回调完成选择。
+ *
+ * 写入走 editingTools.permanentlySetValue(theatre 原生通道):有轨道写帧、
+ * 无轨道写静态,撤销/打帧与内置属性完全一致。
+ *
+ * 数据自给自足(面板与 playground 是两棵 React 树,不依赖闭包注入):
+ * t 来自 studio 树的 i18n provider;库条目来自模块级库单例的订阅;骨架
+ * 族经 obj → placement → 模型库条目异步解析,解析不出则不过滤全可点。
+ *
+ * 框体经 createPortal 挂到 document.body:属性面板在 shadow DOM 里,停靠
+ * 框要盖全画布必须脱离 shadow 根(React context 穿 portal 保留,i18n 照常)。
+ */
+import React from 'react';
+import type { PropTypeConfig_AllSimples } from '@dreamerbird/core/types/public';
+import type { ISimplePropEditorReactProps } from '@dreamerbird/studio/propEditors/simpleEditors/ISimplePropEditorReactProps';
+declare const PosePropEditor: React.FC<ISimplePropEditorReactProps<PropTypeConfig_AllSimples>>;
+export default PosePropEditor;
+//# sourceMappingURL=PosePropEditor.d.ts.map

package/dist/poseMode/PosePropEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PosePropEditor.d.ts","sourceRoot":"","sources":["../../src/poseMode/PosePropEditor.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAiD,MAAM,OAAO,CAAA;AAIrE,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAC,2BAA2B,EAAC,MAAM,2EAA2E,CAAA;AAiB1H,QAAA,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAC5B,2BAA2B,CAAC,yBAAyB,CAAC,CA+HvD,CAAA;AAED,eAAe,cAAc,CAAA"}

package/dist/poseMode/PosePropEditor.js

@@ -0,0 +1,139 @@
+/**
+ * 姿势属性编辑器(2026-10-01 属性面板姿势行 + 框体注册制):经 core 的
+ * editor 配置项 + studio 自定义编辑器注册表,替换 pose 属性在详情面板里
+ * 的值区域。
+ *
+ * 行内显示 = poseDisplayText 三态:T 姿势(空值/绑定)/ 预设名称(库)/
+ * 自定义姿势(双击模型进姿势模式摆的,或选预设后又改过)。点值区域开
+ * 左侧停靠的姿势选择框(不再是 select 式弹框):T 姿势 + 同骨架族库
+ * 预设(异族置灰)——框体就是纯姿势列表,自定义不设选项,只能编辑产生。
+ *
+ * 框体注册制:pickerRegistry 的 'pose' 槽位注册了宿主组件就用宿主的
+ * (props = 组装好的 options/current + onPick/onClose 回调),没注册用内置
+ * PosePickerFrame。库管开/关与数据,宿主组件只画 UI、调回调完成选择。
+ *
+ * 写入走 editingTools.permanentlySetValue(theatre 原生通道):有轨道写帧、
+ * 无轨道写静态,撤销/打帧与内置属性完全一致。
+ *
+ * 数据自给自足(面板与 playground 是两棵 React 树,不依赖闭包注入):
+ * t 来自 studio 树的 i18n provider;库条目来自模块级库单例的订阅;骨架
+ * 族经 obj → placement → 模型库条目异步解析,解析不出则不过滤全可点。
+ *
+ * 框体经 createPortal 挂到 document.body:属性面板在 shadow DOM 里,停靠
+ * 框要盖全画布必须脱离 shadow 根(React context 穿 portal 保留,i18n 照常)。
+ */
+import React, { useContext, useEffect, useMemo, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { useI18n } from '@dreamerbird/studio/i18n';
+import { PopoverAutoCloseLock } from '@dreamerbird/studio/uiComponents/Popover/usePopover';
+import { getLibrary, useLibraryEntries } from '../assetLibrary/library';
+import { useModelThumbUrl } from '../assetLibrary/useModelThumbUrl';
+import { getPlacementEntryForObject } from '../PlacementManager';
+import { buildPoseOptions } from './poseOptions';
+import { poseDisplayText } from './poseDisplayText';
+import { poseEntryName } from '../poseNames';
+import { serializeLibPose } from './poseValue';
+import { isHandPoseEntry } from '../gestureProps';
+import { getRegisteredPicker } from '../pickerRegistry';
+import { PosePickerFrame } from './PosePickerFrame';
+import { getUiConfig } from '../uiConfig';
+// 注册表组件按 AllSimples 声明(注册表对任意 simple 类型开放);
+// pose 属性实为 string,值在使用处收窄
+const PosePropEditor = ({ editingTools, value, obj }) => {
+    const { t } = useI18n();
+    const poseEntries = useLibraryEntries('pose');
+    // 内置姿势由 StaticCatalogSource 目录提供(2026-10-10 去播种),无需触发
+    const [pickerOpen, setPickerOpen] = useState(false);
+    // 值区域 hover 态:对齐 BasicStringInput(静态透明无边框,hover 出底出边)
+    const [valueHovered, setValueHovered] = useState(false);
+    // 停靠框打开期间持父弹框锁:本编辑器也会渲染在时间轴帧弹框里,帧弹框
+    // 有「挪远/点外部自动关」;停靠框 portal 到 body 不在其 DOM 内,不持锁
+    // 的话鼠标一移向停靠框帧弹框就先关,本组件连同停靠框一起被卸载——
+    // 颜色选择器的二级弹框赖同一机制存活。属性面板场景拿到默认空锁,零影响
+    const parentPopoverLock = useContext(PopoverAutoCloseLock);
+    useEffect(() => {
+        if (!pickerOpen)
+            return;
+        const held = parentPopoverLock.takeFocus();
+        return () => held.releaseFocus();
+    }, [pickerOpen, parentPopoverLock]);
+    // 编辑器所属对象的骨架族(obj → placement → 模型库条目),用于过滤异族预设;
+    // 条目本体也留一份——「T 姿势」项的缩略图就用模型自己的图(模型图就是
+    // 按绑定/T 姿势渲染的,语义正好)
+    const [rig, setRig] = useState(undefined);
+    const [modelEntry, setModelEntry] = useState(undefined);
+    useEffect(() => {
+        let cancelled = false;
+        const entry = obj
+            ? getPlacementEntryForObject(obj)
+            : undefined;
+        if (!entry?.libraryEntryId) {
+            setRig(undefined);
+            setModelEntry(undefined);
+            return;
+        }
+        void getLibrary()
+            .getEntry(entry.libraryEntryId)
+            .then((libEntry) => {
+            if (cancelled)
+                return;
+            setRig(libEntry?.rig);
+            setModelEntry(libEntry && 'thumbnailId' in libEntry
+                ? { id: libEntry.id, thumbnailId: libEntry.thumbnailId }
+                : undefined);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [obj]);
+    const poseJson = value ?? '';
+    // 姿势框回归纯身体姿势(2026-10-05):纯手势条目(全是手指骨)挪去
+    // 左手势/右手势选择框;显示文本仍查全表(旧值引用了手势条目也显名)
+    const bodyPoseEntries = useMemo(() => poseEntries.filter((e) => !isHandPoseEntry(e)), [poseEntries]);
+    // 缩略图懒加载(条目带 thumbnailId 时给选择框选项配图)
+    const { getThumbUrl } = useModelThumbUrl();
+    // 显示名:种子条目查 i18n 词典(纯姿势名),用户自存姿势回退条目名原文
+    const nameOf = (e) => poseEntryName(e, t);
+    const { options, current } = buildPoseOptions({
+        poseJson,
+        libEntries: bodyPoseEntries,
+        selectedRig: rig,
+        thumbUrlOf: getThumbUrl,
+        bindThumbUrl: modelEntry ? getThumbUrl(modelEntry) : undefined,
+        nameOf,
+        t,
+    });
+    // 选后不关框(2026-10-05 与用户对齐):框留着可连续换姿势看效果,
+    // 高亮随值刷新;关闭走 ✕/Esc
+    const handlePick = (key) => {
+        editingTools.permanentlySetValue(key === 'bind' ? '' : serializeLibPose(key.slice(4)));
+    };
+    // 每次开框现读注册表:宿主注册/注销无需订阅,下一次开框即生效
+    const Picker = getRegisteredPicker('pose') ?? PosePickerFrame;
+    return (React.createElement(React.Fragment, null,
+        React.createElement("div", { "data-testid": "PosePropValue", title: poseDisplayText({ poseJson, libEntries: poseEntries, nameOf, t }), onClick: () => setPickerOpen(true), onMouseEnter: () => setValueHovered(true), onMouseLeave: () => setValueHovered(false), style: {
+                width: '100%',
+                boxSizing: 'border-box',
+                // 高度对齐 BasicStringInput 的 calc(100% - 4px):不显式撑高,
+                // hover 出底边时会比相邻原生输入框矮一截
+                height: 'calc(100% - 4px)',
+                display: 'flex',
+                alignItems: 'center',
+                padding: '1px 6px',
+                borderRadius: 2,
+                border: `1px solid ${valueHovered ? '#00000059' : 'transparent'}`,
+                background: valueHovered ? '#10101042' : 'transparent',
+                color: 'rgba(255, 255, 255, 0.9)',
+                fontSize: 11,
+                cursor: 'pointer',
+                whiteSpace: 'nowrap',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                userSelect: 'none',
+            } }, poseDisplayText({ poseJson, libEntries: poseEntries, nameOf, t })),
+        pickerOpen &&
+            createPortal(React.createElement(Picker, { options: options, current: current, onPick: handlePick, onClose: () => setPickerOpen(false) }), 
+            // 宿主可配 portal 容器(ui.portalContainer),缺省挂 document.body
+            getUiConfig().portalContainer ?? document.body)));
+};
+export default PosePropEditor;

package/dist/poseMode/controlSpec.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 人形骨架控制点装配表:用 threeIK 的骨名映射(Mixamo/VRM/无前缀预设)
+ * 把模型骨名翻成人形 profile,产出标准控制点集合。关键骨(REQUIRED_HUMANOID_
+ * BONES:髋/脊柱/头/肩/四肢)缺任一 → null = 不支持摆姿势(菜单置灰、双击静默)。
+ */
+import { Vector3 } from 'three';
+import type { Object3D, Bone } from 'three';
+import type { ControlPointSpec } from '@dreamerbird/threeik/controls';
+/** 父不是 Bone 的第一根 Bone = 骨架根(SkeletonRig 的构造参数) */
+export declare function findRootBone(root: Object3D): Bone | null;
+/**
+ * 骨架世界高度(头骨 Y − 最低脚骨 Y)÷ 参考人形高 → 控制点尺寸倍率。
+ * threeIK 的球/环默认半径按 ~1.7 单位人形设计;场景里模型缩放不同(如 Y_Bot 0.026
+ * 缩放出 3.58 单位骨架)时等比缩放才看得见、点得中。非人形/测不出高度时返回 1。
+ */
+export declare function measureSkeletonScale(root: Object3D): number;
+/**
+ * 人形解剖学朝向(世界坐标):脊柱向上 × (右髋−左髋) = 面朝方向。
+ * 「模型局部前方是哪根轴」各家约定不同(Mixamo +Z、FBX 转出的可能有 -90°X 骨架节点)、
+ * 放置组还会任意旋转——靠髋/脊柱骨的世界位置反推,与命名约定、局部轴向、放置旋转全无关。
+ * 注视球生在脸前还是脑后、肘/膝 pole 朝哪边,全看这个朝向;测不出(非人形/退化)→ null,
+ * 调用方回退库默认 (0,0,-1)。
+ */
+export declare function deriveHumanoidFacing(root: Object3D): Vector3 | null;
+export declare function resolveControlSpec(root: Object3D, facing?: Vector3): ControlPointSpec[] | null;
+//# sourceMappingURL=controlSpec.d.ts.map

package/dist/poseMode/controlSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controlSpec.d.ts","sourceRoot":"","sources":["../../src/poseMode/controlSpec.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,OAAO,EAAC,OAAO,EAAC,MAAM,OAAO,CAAA;AAC7B,OAAO,KAAK,EAAC,QAAQ,EAAE,IAAI,EAAC,MAAM,OAAO,CAAA;AAEzC,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,+BAA+B,CAAA;AAGnE,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CAQxD;AAKD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAqB3D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,IAAI,CAqBnE;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,EACd,MAAM,GAAE,OAA+B,GACtC,gBAAgB,EAAE,GAAG,IAAI,CA2E3B"}

package/dist/poseMode/controlSpec.js

@@ -0,0 +1,157 @@
+// packages/camera-studio/src/poseMode/controlSpec.ts
+/**
+ * 人形骨架控制点装配表:用 threeIK 的骨名映射(Mixamo/VRM/无前缀预设)
+ * 把模型骨名翻成人形 profile,产出标准控制点集合。关键骨(REQUIRED_HUMANOID_
+ * BONES:髋/脊柱/头/肩/四肢)缺任一 → null = 不支持摆姿势(菜单置灰、双击静默)。
+ */
+import { Vector3 } from 'three';
+import { suggestBoneMap } from '@dreamerbird/threeik';
+import { collectBoneNames } from '../assetLibrary/rig';
+/** 父不是 Bone 的第一根 Bone = 骨架根(SkeletonRig 的构造参数) */
+export function findRootBone(root) {
+    let found = null;
+    root.traverse((o) => {
+        if (found)
+            return;
+        const asBone = o;
+        if (asBone.isBone && !o.parent?.isBone)
+            found = asBone;
+    });
+    return found;
+}
+/** threeIK 控制点默认尺寸按其 playground 的米制人形(~1.7 单位高)标定 */
+const REFERENCE_HUMANOID_HEIGHT = 1.7;
+/**
+ * 骨架世界高度(头骨 Y − 最低脚骨 Y)÷ 参考人形高 → 控制点尺寸倍率。
+ * threeIK 的球/环默认半径按 ~1.7 单位人形设计;场景里模型缩放不同(如 Y_Bot 0.026
+ * 缩放出 3.58 单位骨架)时等比缩放才看得见、点得中。非人形/测不出高度时返回 1。
+ */
+export function measureSkeletonScale(root) {
+    const names = collectBoneNames(root);
+    if (names.length === 0)
+        return 1;
+    const { map, coverage } = suggestBoneMap(names);
+    if (coverage < 1)
+        return 1;
+    root.updateWorldMatrix(true, true);
+    const worldY = (profile) => {
+        const name = map.findModelBone(profile);
+        if (!name)
+            return null;
+        const obj = root.getObjectByName(name);
+        return obj ? obj.getWorldPosition(new Vector3()).y : null;
+    };
+    const head = worldY('Head');
+    const footL = worldY('LeftFoot');
+    const footR = worldY('RightFoot');
+    if (head === null)
+        return 1;
+    const ground = Math.min(footL ?? Infinity, footR ?? Infinity);
+    if (!Number.isFinite(ground))
+        return 1;
+    const height = head - ground;
+    if (!(height > 0.01))
+        return 1;
+    return Math.min(Math.max(height / REFERENCE_HUMANOID_HEIGHT, 0.25), 8);
+}
+/**
+ * 人形解剖学朝向(世界坐标):脊柱向上 × (右髋−左髋) = 面朝方向。
+ * 「模型局部前方是哪根轴」各家约定不同(Mixamo +Z、FBX 转出的可能有 -90°X 骨架节点)、
+ * 放置组还会任意旋转——靠髋/脊柱骨的世界位置反推,与命名约定、局部轴向、放置旋转全无关。
+ * 注视球生在脸前还是脑后、肘/膝 pole 朝哪边,全看这个朝向;测不出(非人形/退化)→ null,
+ * 调用方回退库默认 (0,0,-1)。
+ */
+export function deriveHumanoidFacing(root) {
+    const names = collectBoneNames(root);
+    if (names.length === 0)
+        return null;
+    const { map, coverage } = suggestBoneMap(names);
+    if (coverage < 1)
+        return null;
+    root.updateWorldMatrix(true, true);
+    const worldPosOf = (profile) => {
+        const name = map.findModelBone(profile);
+        const obj = name ? root.getObjectByName(name) : null;
+        return obj ? obj.getWorldPosition(new Vector3()) : null;
+    };
+    const hips = worldPosOf('Hips');
+    const upper = worldPosOf('Neck') ?? worldPosOf('Head');
+    const upLegL = worldPosOf('LeftUpperLeg');
+    const upLegR = worldPosOf('RightUpperLeg');
+    if (!hips || !upper || !upLegL || !upLegR)
+        return null;
+    const spineUp = upper.sub(hips);
+    const leftToRight = upLegR.sub(upLegL);
+    if (spineUp.lengthSq() < 1e-10 || leftToRight.lengthSq() < 1e-10)
+        return null;
+    const forward = spineUp.normalize().cross(leftToRight.normalize());
+    return forward.lengthSq() < 1e-10 ? null : forward.normalize();
+}
+export function resolveControlSpec(root, facing = new Vector3(0, 0, -1)) {
+    const names = collectBoneNames(root);
+    if (names.length === 0)
+        return null;
+    const { map, coverage } = suggestBoneMap(names);
+    if (coverage < 1)
+        return null; // coverage 只算关键骨;1 = 关键骨全映射
+    const bone = (profile) => map.findModelBone(profile);
+    const optional = (profile) => map.findModelBone(profile);
+    // 肘/膝 pole 初始方向提示(世界坐标):肘朝后、膝朝前。世界矩阵先刷新,
+    // 保证菜单场景外(测试/刚进会话)也能取到正确位置。
+    root.updateWorldMatrix(true, true);
+    const worldPosOf = (name) => {
+        const obj = root.getObjectByName(name);
+        return obj.getWorldPosition(new Vector3());
+    };
+    const behind = facing.clone().normalize().multiplyScalar(-0.25);
+    const ahead = facing.clone().normalize().multiplyScalar(0.25);
+    const armL = [bone('LeftUpperArm'), bone('LeftLowerArm'), bone('LeftHand')];
+    const armR = [bone('RightUpperArm'), bone('RightLowerArm'), bone('RightHand')];
+    const legL = [bone('LeftUpperLeg'), bone('LeftLowerLeg'), bone('LeftFoot')];
+    const legR = [bone('RightUpperLeg'), bone('RightLowerLeg'), bone('RightFoot')];
+    const neck = optional('Neck');
+    const chest = optional('UpperChest') ?? optional('Chest') ?? bone('Spine');
+    const limb = (name, [rootBone, middleBone, endBone], poleOffset) => ({
+        kind: 'limb',
+        name,
+        rootBone,
+        middleBone,
+        endBone,
+        endRotation: true,
+        rootRotation: true,
+        pole: { position: worldPosOf(middleBone).add(poleOffset) },
+    });
+    return [
+        { kind: 'root', name: 'hips', bone: bone('Hips'), rotation: true },
+        limb('armL', armL, behind),
+        limb('armR', armR, behind),
+        limb('legL', legL, ahead),
+        limb('legR', legR, ahead),
+        // 排序即语义:脊柱链先解,胸口环在弯腰之上拧上半身,头部注视最后重新瞄准
+        {
+            kind: 'chain',
+            name: 'spine',
+            rootBone: bone('Spine'),
+            endBone: neck ?? bone('Head'),
+        },
+        { kind: 'bone', name: 'chest', bone: chest },
+        ...(neck
+            ? [
+                {
+                    kind: 'lookAt',
+                    name: 'head',
+                    rootBone: neck,
+                    endBone: bone('Head'),
+                    // 0.2.0 头顶摇杆:球挪到头顶当摇杆帽(不挡脸),前推低头/后拉仰头/左右推
+                    // 左右转,偏角 1:1;无目标点——偏角直驱头颈分摊旋转(与 E 环同款机制)
+                    joystick: true,
+                    // 球离头距离走库默认项:PoseModeRig 的 defaults.joystickRadius(0.16×倍率,
+                    // 贴头)——0.2.1 起 joystick 球距与注视球距(lookAtRadius)语义分开
+                    // 0.1.0 头环带脖子:E 出头骨旋转环,颈先分摊 40%、头补足,
+                    // 松手注视球绕颈根按拖拽增量重坐(朝向不跳)
+                    rotateShare: 0.4,
+                },
+            ]
+            : []),
+    ];
+}

package/dist/poseMode/controlSpec.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=controlSpec.test.d.ts.map

package/dist/poseMode/controlSpec.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controlSpec.test.d.ts","sourceRoot":"","sources":["../../src/poseMode/controlSpec.test.ts"],"names":[],"mappings":""}