@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/placementPoseProps.test.js

@@ -0,0 +1,35 @@
+// packages/camera-studio/src/placementPoseProps.test.ts
+/**
+ * PlacementManager 姿势注册改造的可测纯件:
+ * - countLibraryEntryUsage 的姿势计数对旧裸 id 与新 {kind:'lib'} 都算使用
+ * - 注册形态:pose = hidden + 自定义插值器;poseOverride 保留但 hidden(迁移过渡)
+ */
+import { isPoseEntryUsed, posePropConfigShape, shouldApplyPoseDuringPlayback, shouldApplyPoseWhenIdle, } from './placementPoseProps';
+import { poseInterpolate } from './poseMode/poseInterpolate';
+test('isPoseEntryUsed:旧裸 id 与新格式 lib 引用都算使用;custom 不算', () => {
+    expect(isPoseEntryUsed('entry_a', 'entry_a')).toBe(true);
+    expect(isPoseEntryUsed('{"kind":"lib","id":"entry_a"}', 'entry_a')).toBe(true);
+    expect(isPoseEntryUsed('{"kind":"custom","bones":{}}', 'entry_a')).toBe(false);
+    expect(isPoseEntryUsed('', 'entry_a')).toBe(false);
+});
+test('posePropConfigShape:editor=pose + poseInterpolate + 空默认(属性行化)', () => {
+    const shape = posePropConfigShape();
+    expect(shape.defaultValue).toBe('');
+    expect(shape.opts.editor).toBe('pose');
+    expect(shape.opts.interpolate).toBe(poseInterpolate);
+    expect(typeof shape.opts.label).toBe('function');
+});
+test('播放中只在有姿势轨道时逐帧应用姿势(spec §7.1)', () => {
+    expect(shouldApplyPoseDuringPlayback(true)).toBe(true);
+    expect(shouldApplyPoseDuringPlayback(false)).toBe(false);
+});
+test('空闲应用门禁:播放中不应用;姿势会话中不抢骨骼(退出后由依赖重跑补刷)', () => {
+    // 空闲且非姿势模式 = 应用(值切换/撤销重做/会话退出补刷都走这里)
+    expect(shouldApplyPoseWhenIdle(false, false)).toBe(true);
+    // 播放中 = 不应用(mixer/播放求值独占)
+    expect(shouldApplyPoseWhenIdle(true, false)).toBe(false);
+    // 姿势模式会话中 = 不应用(IK 骨架每帧重解算,applyPose 会被压回;
+    // 会话期间值被弹框/撤销/同步改掉时靠退出后的重跑补刷,不在会话里抢)
+    expect(shouldApplyPoseWhenIdle(false, true)).toBe(false);
+    expect(shouldApplyPoseWhenIdle(true, true)).toBe(false);
+});

package/dist/poseMode/PoseModeBar.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 摆姿势浮动小条:挂在被摆模型头顶(Head 骨骼世界位置 + 等比偏移),
+ * 跟着模型/相机走(drei Html 把 DOM 钉到 3D 位置,屏幕恒定大小)。
+ * 内容只有 [移动|旋转] 两个按钮(悬停提示保留);帧模式判定仍在
+ * PoseModeRig 照常进行,只是不再显示在条上。
+ *
+ * 移动/旋转与 W/E 键共用 poseSession 的 manipulatorMode(单一状态源):
+ * 按钮 setPoseManipulatorMode → 本组件订阅刷新高亮;PoseModeRig 同一
+ * 订阅转发 threeIK——两条路径永远一致,不存在"按钮瞎"或"环不跟着切"。
+ *
+ * 退出手势(快捷键/双击空白)在 App 与 PoseModeRig。
+ */
+import React from 'react';
+import type { Group } from 'three';
+export declare function PoseModeBar({ instance, }: {
+    instance: Group;
+}): React.JSX.Element | null;
+//# sourceMappingURL=PoseModeBar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PoseModeBar.d.ts","sourceRoot":"","sources":["../../src/poseMode/PoseModeBar.tsx"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AACH,OAAO,KAA6C,MAAM,OAAO,CAAA;AASjE,OAAO,KAAK,EAAC,KAAK,EAAW,MAAM,OAAO,CAAA;AAsE1C,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,KAAK,CAAA;CAChB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,CAkE3B"}

package/dist/poseMode/PoseModeBar.js

@@ -0,0 +1,127 @@
+// packages/camera-studio/src/poseMode/PoseModeBar.tsx
+/**
+ * 摆姿势浮动小条:挂在被摆模型头顶(Head 骨骼世界位置 + 等比偏移),
+ * 跟着模型/相机走(drei Html 把 DOM 钉到 3D 位置,屏幕恒定大小)。
+ * 内容只有 [移动|旋转] 两个按钮(悬停提示保留);帧模式判定仍在
+ * PoseModeRig 照常进行,只是不再显示在条上。
+ *
+ * 移动/旋转与 W/E 键共用 poseSession 的 manipulatorMode(单一状态源):
+ * 按钮 setPoseManipulatorMode → 本组件订阅刷新高亮;PoseModeRig 同一
+ * 订阅转发 threeIK——两条路径永远一致,不存在"按钮瞎"或"环不跟着切"。
+ *
+ * 退出手势(快捷键/双击空白)在 App 与 PoseModeRig。
+ */
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import styled from 'styled-components';
+import { Html } from '@react-three/drei';
+import { useFrame } from '@react-three/fiber';
+import { ArrowClockwise, ArrowsOutCardinal } from '@phosphor-icons/react';
+import ToolbarIconButton from '@dreamerbird/studio/uiComponents/toolbar/ToolbarIconButton';
+import ToolbarSwitchSelectContainer from '@dreamerbird/studio/uiComponents/toolbar/ToolbarSwitchSelectContainer';
+import { onLanguageChange, translate } from '@dreamerbird/studio/i18n';
+import { suggestBoneMap } from '@dreamerbird/threeik';
+import { Vector3 } from 'three';
+import { collectBoneNames } from '../assetLibrary/rig';
+import { measureSkeletonScale } from './controlSpec';
+import { getPoseManipulatorMode, onPoseManipulatorModeChange, setPoseManipulatorMode, usePoseSelectionModes, } from './poseSession';
+/** 头骨上方偏移(乘骨架等比倍率):离头顶远一截,编辑头颈时不挡视线 */
+const HEAD_OFFSET = 0.6;
+/** 每帧复用的临时向量(避免逐帧分配) */
+const tmpVec = new Vector3();
+/** 原生 ToolbarIconButton + tooltip(样式照抄 TopToolbar 的 Btn,保持观感一致) */
+const ModeBtn = styled(ToolbarIconButton) `
+  /* tooltip:按钮 relative,气泡钉在正下方 */
+  & > .tip {
+    position: absolute;
+    top: calc(100% + 8px);
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 10000;
+    padding: 6px 8px;
+    border-radius: 4px;
+    box-shadow: rgb(0 0 0 / 25%) 0px 2px 4px;
+    backdrop-filter: blur(8px) saturate(300%) contrast(65%) brightness(55%);
+    background-color: rgb(45 46 66 / 50%);
+    border: 0.5px solid rgb(86 100 110 / 46%);
+    color: var(--theatre-text-primary, #ffffff);
+    font-size: 11px;
+    font-weight: 400;
+    line-height: 1.5;
+    white-space: nowrap;
+    text-align: left;
+    pointer-events: none;
+    opacity: 0;
+    visibility: hidden;
+    transition:
+      opacity 0.15s ease 0.25s,
+      visibility 0.15s ease 0.25s;
+    .hint {
+      display: block;
+      color: var(--theatre-text-secondary, #cccccc);
+    }
+  }
+  &:hover > .tip {
+    opacity: 1;
+    visibility: visible;
+  }
+`;
+const MODES = [
+    {
+        mode: 'move',
+        icon: ArrowsOutCardinal,
+        labelKey: 'pg.gizmo.translate',
+        hintKey: 'pg.posebar.move.hint',
+    },
+    {
+        mode: 'rotate',
+        icon: ArrowClockwise,
+        labelKey: 'pg.gizmo.rotate',
+        hintKey: 'pg.posebar.rotate.hint',
+    },
+];
+export function PoseModeBar({ instance, }) {
+    const anchorRef = useRef(null);
+    // Head 是必映射骨(覆盖率不足根本进不了会话),查不到属防御分支:不挂小条
+    const { headBone, sizeScale } = useMemo(() => {
+        const { map } = suggestBoneMap(collectBoneNames(instance));
+        const name = map.findModelBone('Head');
+        const bone = name
+            ? instance.getObjectByName(name) ?? null
+            : null;
+        return { headBone: bone, sizeScale: measureSkeletonScale(instance) };
+    }, [instance]);
+    // 当前模式订阅共享状态:W/E 键与小条按钮同一入口,高亮永远同步
+    const [mode, setMode] = useState(getPoseManipulatorMode());
+    useEffect(() => onPoseManipulatorModeChange(setMode), []);
+    // 选中目标的模式支持集:单模式点(纯旋转环/纯移动球)禁用不可用按钮
+    const selModes = usePoseSelectionModes();
+    // 语言热切换:Canvas 是 r3f 独立渲染根,context 不桥接,useT 拿不到
+    // DOM 树的 I18nProvider;translate 是模块级函数、调用时读当前语言,
+    // 再订阅语言变化触发重渲染即可
+    const [, setLangTick] = useState(0);
+    useEffect(() => onLanguageChange(() => setLangTick((n) => n + 1)), []);
+    // 每帧把锚点组同步到头骨世界位置。渲染时机不用管:拖球/转视角都会
+    // invalidate(demand 帧循环),静止时锚点不动、无需更新。
+    // 锚点组挂在放置组(自带位移/缩放,如 Y_Bot 0.026)里,position 是父级
+    // 本地坐标:必须先在世界空间取头骨位置+偏移,再转回父级本地空间——
+    // 直接写世界坐标会被父级缩放压到模型脚下(实测踩过)
+    useFrame(() => {
+        const anchor = anchorRef.current;
+        if (!anchor || !headBone)
+            return;
+        headBone.getWorldPosition(tmpVec);
+        tmpVec.y += HEAD_OFFSET * sizeScale;
+        if (anchor.parent)
+            anchor.parent.worldToLocal(tmpVec);
+        anchor.position.copy(tmpVec);
+    });
+    if (!headBone)
+        return null;
+    return (React.createElement("group", { ref: anchorRef },
+        React.createElement(Html, { center: true, zIndexRange: [15, 0], wrapperClass: "pose-bar-wrapper" },
+            React.createElement(ToolbarSwitchSelectContainer, null, MODES.map(({ mode: m, icon: Icon, labelKey, hintKey }) => (React.createElement(ModeBtn, { key: m, className: mode === m ? 'selected' : '', disabled: !selModes[m], onClick: () => setPoseManipulatorMode(m) },
+                React.createElement(Icon, { size: 16 }),
+                React.createElement("span", { className: "tip" },
+                    translate(labelKey),
+                    React.createElement("span", { className: "hint" }, translate(hintKey))))))))));
+}

package/dist/poseMode/PoseModeRig.d.ts

@@ -0,0 +1,9 @@
+import type { ISheet, ISheetObject } from '@dreamerbird/core';
+import type { Group } from 'three';
+export declare function PoseModeRig({ instance, sheetObject, placementKey, sheet, }: {
+    instance: Group;
+    sheetObject: ISheetObject<any>;
+    placementKey: string;
+    sheet: ISheet;
+}): null;
+//# sourceMappingURL=PoseModeRig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PoseModeRig.d.ts","sourceRoot":"","sources":["../../src/poseMode/PoseModeRig.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,MAAM,EAAE,YAAY,EAAC,MAAM,mBAAmB,CAAA;AAE3D,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,OAAO,CAAA;AAoChC,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,KAAK,GACN,EAAE;IACD,QAAQ,EAAE,KAAK,CAAA;IACf,WAAW,EAAE,YAAY,CAAC,GAAG,CAAC,CAAA;IAC9B,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;CACd,GAAG,IAAI,CA4RP"}

package/dist/poseMode/PoseModeRig.js

@@ -0,0 +1,300 @@
+// packages/camera-studio/src/poseMode/PoseModeRig.tsx
+/**
+ * 姿势模式运行时:SkeletonRig + threeIK 控制点的生命周期、每帧求解、退出提交。
+ * 会话命中时由 PlacedModelCore 挂载;卸载(模型删除/会话切换)即 dispose 干净。
+ *
+ * 帧更新契约(threeIK README):基准姿势在进入时 captureBasePose 一次
+ * (= 当前姿势,含 poseOverride/库姿势/绑定姿势;不接 mixer 时无需每帧采),
+ * 之后每帧 rig.update + ctl.update;demand 帧循环下只在按下指针期间续帧。
+ */
+import { useEffect, useRef } from 'react';
+import { useFrame, useThree } from '@react-three/fiber';
+import { getStudioSync, onChange, val } from '@dreamerbird/core';
+import { Raycaster, Vector2, Vector3 } from 'three';
+import { SkeletonRig } from '@dreamerbird/threeik';
+import { createSkeletonControls } from '@dreamerbird/threeik/controls';
+import { capturePose } from '../assetLibrary/pose';
+import { deriveHumanoidFacing, measureSkeletonScale, resolveControlSpec, findRootBone, } from './controlSpec';
+import { anyControlDragging } from './dragState';
+import { determinePoseFrameMode } from './poseFrame';
+import { getPoseKeyframePositions, writePoseKeyframe } from './poseTrack';
+import { serializeCustomPose } from './poseValue';
+import { supportedModesForSelection, resolvePoseModeSwitch, } from './selectionModes';
+import { clearPoseSession, clearPoseSessionIfCurrent, getPoseManipulatorMode, getPoseSelectionModes, getPoseSessionFrame, isPoseDirty, markPoseDirty, onPoseExitRequested, onPoseManipulatorModeChange, setPoseHitTester, setPoseManipulatorMode, setPoseSelectionModes, setPoseSessionFrame, } from './poseSession';
+import { registerPoseSessionRig } from '../agent/runtime/poseSessionRuntime';
+export function PoseModeRig({ instance, sheetObject, placementKey, sheet, }) {
+    const gl = useThree((s) => s.gl);
+    const camera = useThree((s) => s.camera);
+    const scene = useThree((s) => s.scene);
+    // drei makeDefault 的轨道控制器:拖控制球期间锁住,防视角跟转
+    const orbitControls = useThree((s) => s.controls);
+    const invalidate = useThree((s) => s.invalidate);
+    const rigRef = useRef(null);
+    const ctlRef = useRef(null);
+    const pressingRef = useRef(false);
+    const dirtyRef = useRef(false);
+    const controlNamesRef = useRef([]);
+    // 装配表/选中名:useFrame 轮询选中态用(支持集推导 + 单模式点自动切换)
+    const specRef = useRef(null);
+    const lastSelectedRef = useRef(null);
+    useEffect(() => {
+        // 播放中进会话:先暂停(spec §8.1.1)——否则播放头锁与播放钟打架,
+        // Rig 的 useFrame 播放时早退 IK 永不求解;脏 Esc 还会把 mixer 帧
+        // 烤进姿势关键帧。必须在 determinePoseFrameMode 读 position 之前,
+        // 保证读到的播放头稳定
+        if (val(sheet.sequence.pointer.playing))
+            sheet.sequence.pause();
+        const rootBone = findRootBone(instance);
+        // 解剖学朝向(髋×脊柱反推,与模型局部轴向约定/放置旋转无关):
+        // 不传则库默认 (0,0,-1)——Y Bot 这类面朝 +Z 的模型注视球会生在脑后、拖球镜像
+        const facing = deriveHumanoidFacing(instance) ?? new Vector3(0, 0, -1);
+        const spec = resolveControlSpec(instance, facing);
+        if (!rootBone || !spec) {
+            // 入口已拦(菜单置灰/双击静默),这里是防御:直接清会话不挂载
+            clearPoseSession();
+            return;
+        }
+        const rig = new SkeletonRig(rootBone);
+        rigRef.current = rig;
+        specRef.current = spec;
+        lastSelectedRef.current = null;
+        rig.on('warning', (payload) => console.warn('[poseMode]', payload?.message));
+        // 基准 = 当前姿势:没被控制点覆盖的骨骼保持原样,不弹回绑定姿势
+        rig.captureBasePose();
+        controlNamesRef.current = spec.map((c) => c.name);
+        dirtyRef.current = false;
+        const sizeScale = measureSkeletonScale(instance);
+        // 尺寸语义随 0.1.0 换芯拆分:ringRadius/ballRadius 已变成操纵器屏尺寸倍率
+        // (÷类默认后传给 TransformControls.size,gizmo 屏幕恒定大小)——乘 sizeScale
+        // 会把 gizmo 放大成 sizeScale 倍屏尺寸(0.0.1 的世界尺寸语义已作废),保持默认;
+        // rootRadius(重心活动球域)、lookAtRadius(注视球恒距)与 joystickRadius(头顶摇杆
+        // 球离头距离,0.2.1 起独立默认项)仍是世界单位语义,随骨架等比
+        const ctl = createSkeletonControls({
+            rig,
+            scene,
+            camera,
+            dom: gl.domElement,
+            controls: spec,
+            facing,
+            defaults: {
+                rootRadius: 0.4 * sizeScale,
+                lookAtRadius: 0.35 * sizeScale,
+                // 0.16×倍率 ≈ 球心嵌头顶表面内侧:球收进头部轮廓内偏顶,不悬空(0.35 注视
+                // 距离会悬在头顶上方一截);球 depthTest:false 透显,嵌入头内仍可见可拖
+                // (命中是纯数学判定,头部网格不挡);推杆时球沿贴头球面滑动
+                joystickRadius: 0.16 * sizeScale,
+            },
+            dragControl: {
+                lock: () => {
+                    if (orbitControls)
+                        orbitControls.enabled = false;
+                },
+                unlock: () => {
+                    if (orbitControls)
+                        orbitControls.enabled = true;
+                },
+            },
+            // 0.1.0 起装配器内置 Maya 热键(W/E/Escape)默认绑 window:W/E 与我们
+            // 自监听(经 poseSession 共享状态、浮条高亮同源)双触发,Escape 会抢
+            // 退出会话。全关,自绑路径不变
+            hotkeys: false,
+        });
+        ctlRef.current = ctl;
+        // 视觉球网格随骨架等比放大(ballRadius 保持类默认 → manipulatorSize 恒 1,
+        // gizmo 标准屏尺寸)。multiplyScalar 而非 setScalar:标记球(胸口/肩髋)自带
+        // 0.7 身份缩放(MARKER_SCALE),要保住相对大小;DragTarget 只在射线检测读
+        // ball.scale,从不覆写,外部设置安全
+        for (const t of ctl.targets)
+            t.ball.scale.multiplyScalar(sizeScale);
+        // 四肢 pole(PoleOrbit)不是 DragTarget、不在 ctl.targets,按 spec 的 limb 名
+        // 从句柄取出补同样的等比;其射线容差随相机距离走(cameraDist×0.011,远大于
+        // 球径),网格等比后点按区域不受影响
+        for (const c of spec) {
+            if (c.kind !== 'limb')
+                continue;
+            ctl
+                .get(c.name)
+                ?.pole.ball.scale.multiplyScalar(sizeScale);
+        }
+        // 调试/自动化验证挂钩(同 __cameraShot):浏览器冒烟直接读选中态
+        // (getSelected)与各控制球世界坐标,免去按像素猜点
+        ;
+        window.__poseDebug = { ctl, camera };
+        // threeIK 0.0.1 无内置热键:自监听 W/E 经 poseSession 共享状态切操纵器
+        // 模式(浮动小条按钮同一入口,UI 高亮因此永远同步;直接调 ctl 会让小条瞎)。
+        // Esc 未被监听,天然留给 App 退出会话。
+        const onKey = (ev) => {
+            if (ev.repeat)
+                return;
+            const target = ev.target;
+            if (target &&
+                (target.tagName === 'INPUT' ||
+                    target.tagName === 'TEXTAREA' ||
+                    target.isContentEditable))
+                return;
+            // 单模式点门禁:与浮条按钮禁用同一数据源,快捷键也不许切到不可用模式
+            const support = getPoseSelectionModes();
+            if (ev.code === 'KeyW') {
+                if (!support.move)
+                    return;
+                setPoseManipulatorMode('move');
+            }
+            else if (ev.code === 'KeyE') {
+                if (!support.rotate)
+                    return;
+                setPoseManipulatorMode('rotate');
+            }
+            else
+                return;
+            invalidate(); // demand 帧循环:无指针按下时补帧,环/箭头立刻可见
+        };
+        window.addEventListener('keydown', onKey);
+        // 共享状态 → threeIK:小条按钮切换时转发;进会话用记住的偏好初始化
+        ctl.setManipulatorMode(getPoseManipulatorMode());
+        const offMode = onPoseManipulatorModeChange((m) => {
+            ctl.setManipulatorMode(m);
+            invalidate();
+        });
+        // 双击空白退出的命中测试:点在被摆模型或控制球上不算空白
+        const raycaster = new Raycaster();
+        const ndc = new Vector2();
+        setPoseHitTester(({ clientX, clientY }) => {
+            const rect = gl.domElement.getBoundingClientRect();
+            ndc.set(((clientX - rect.left) / rect.width) * 2 - 1, -(((clientY - rect.top) / rect.height) * 2 - 1));
+            raycaster.setFromCamera(ndc, camera);
+            const balls = ctl.targets.map((t) => t.ball);
+            return raycaster.intersectObjects([instance, ...balls], true).length > 0;
+        });
+        // 帧模式判定(spec §8.1):贴网格后帧上=编辑、帧间=新建;底姿由
+        // 既有应用 effect 保证(非播放时画面恒为播放头求值,所见即所编)
+        const frame = determinePoseFrameMode(getPoseKeyframePositions(sheetObject), sheet.sequence.position, (t) => sheet.sequence.closestGridPosition(t));
+        sheet.sequence.position = frame.position;
+        setPoseSessionFrame(placementKey, frame);
+        // 锁播放头(spec §8.1.4):会话期间 position 被挪动即拉回会话时刻
+        const offPosition = onChange(sheet.sequence.pointer.position, (pos) => {
+            if (Math.abs(pos - frame.position) > 1e-6) {
+                sheet.sequence.position = frame.position;
+            }
+        });
+        // 退出提交:捕获实时骨骼 → 写姿势轨关键帧(可撤销,经 writePoseKeyframe)。
+        // 与 Agent poses.session.commit 共用——本函数即登记进
+        // poseSessionRuntime 的 commit 句柄;Esc/双击空白/播放自动退出
+        // 走 requestPoseExit → 同一函数,行为不变。
+        const commitSession = () => {
+            const studio = getStudioSync();
+            // 脏检查:没拖过控制点就不提交(threeIK 首解有微小漂移,
+            // 空进空出写回会产生幻影撤销步;语义对齐 modalGrab 的 moved)。
+            // 双通道或:dirtyRef 由 isDragging 轮询记(帧间隙完整的拖动),
+            // isPoseDirty 由 pointerdown 事件记(同帧间隙的按下-拖-松,轮询漏检)
+            if (studio && (dirtyRef.current || isPoseDirty())) {
+                const bones = capturePose(instance);
+                // 写帧(spec §7.2):帧上=覆盖、帧间=新建、无轨=建轨+首帧;
+                // 先把播放头钉回会话时刻(锁定期间理论不动,双保险)
+                const frame = getPoseSessionFrame();
+                if (frame)
+                    sheet.sequence.position = frame.position;
+                writePoseKeyframe(sheetObject, serializeCustomPose(bones));
+            }
+            clearPoseSession();
+        };
+        const offExit = onPoseExitRequested((key) => {
+            if (key !== placementKey)
+                return;
+            commitSession();
+        });
+        // Agent 姿势会话句柄(poses.session.commit/cancel):commit 与 UI 退出
+        // 同一提交路径;cancel 不写回,会话清除后姿势应用 effect 把当前值
+        // 补刷回骨骼(poseModeActive 翻转触发,见 PlacementManager)
+        const unregisterSessionRig = registerPoseSessionRig(placementKey, {
+            commit: commitSession,
+            cancel: () => clearPoseSession(),
+        });
+        invalidate(); // 进姿势模式首帧:控制球立刻可见
+        return () => {
+            unregisterSessionRig();
+            offExit();
+            offMode();
+            offPosition();
+            setPoseHitTester(null);
+            window.removeEventListener('keydown', onKey);
+            ctl.dispose();
+            ctlRef.current = null;
+            rigRef.current = null;
+            specRef.current = null;
+            lastSelectedRef.current = null;
+            delete window.__poseDebug;
+            // 会话外因素卸载(模型被删等):实例已毁,跳过提交只清会话态。
+            // 按键清:A→B 直接切换时 session 已是 B,不能把它抹掉(切换坍塌)
+            clearPoseSessionIfCurrent(placementKey);
+            invalidate();
+        };
+    }, [
+        instance,
+        sheetObject,
+        placementKey,
+        scene,
+        camera,
+        gl,
+        orbitControls,
+        invalidate,
+    ]);
+    // demand 帧循环:按下指针期间逐帧求解+续帧,松开即停
+    useEffect(() => {
+        const dom = gl.domElement;
+        const raycaster = new Raycaster();
+        const ndc = new Vector2();
+        const down = (ev) => {
+            // 只有按中控制球才记脏:isDragging 轮询会漏同帧间隙的按下-拖-松,
+            // 由这里兜底;空白/模型身上的按下(含双击空白退出的第一击)不记——
+            // 否则转下视角、退出手势本身都会制造幻影提交
+            const ctl = ctlRef.current;
+            if (ctl) {
+                const rect = dom.getBoundingClientRect();
+                ndc.set(((ev.clientX - rect.left) / rect.width) * 2 - 1, -(((ev.clientY - rect.top) / rect.height) * 2 - 1));
+                raycaster.setFromCamera(ndc, camera);
+                const balls = ctl.targets.map((t) => t.ball);
+                if (raycaster.intersectObjects(balls, true).length > 0)
+                    markPoseDirty();
+            }
+            pressingRef.current = true;
+            invalidate();
+        };
+        const up = () => {
+            pressingRef.current = false;
+            invalidate(); // 松手补一帧:钳制回弹落定
+        };
+        dom.addEventListener('pointerdown', down);
+        window.addEventListener('pointerup', up);
+        return () => {
+            dom.removeEventListener('pointerdown', down);
+            window.removeEventListener('pointerup', up);
+        };
+    }, [gl, camera, invalidate]);
+    useFrame((_, delta) => {
+        const rig = rigRef.current;
+        const ctl = ctlRef.current;
+        if (!rig || !ctl)
+            return;
+        if (val(sheet.sequence.pointer.playing))
+            return; // 播放时 mixer 写骨骼,不抢
+        rig.update(delta);
+        ctl.update();
+        // 选中态轮询:threeIK 无选中事件,getSelected() 是便宜字段读。
+        // 变化时刷新支持集(浮条禁用)并自动切到可用模式(单模式点)
+        const sel = ctl.getSelected();
+        if (sel !== lastSelectedRef.current) {
+            lastSelectedRef.current = sel;
+            const support = supportedModesForSelection(specRef.current ?? [], sel);
+            setPoseSelectionModes(support);
+            const next = resolvePoseModeSwitch(support, getPoseManipulatorMode());
+            if (next)
+                setPoseManipulatorMode(next);
+        }
+        if (!dirtyRef.current && anyControlDragging(ctl, controlNamesRef.current)) {
+            dirtyRef.current = true;
+        }
+        if (pressingRef.current)
+            invalidate();
+    });
+    return null;
+}

package/dist/poseMode/PosePickerFrame.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 内置姿势选择框体(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';
+/**
+ * 框体的宽松 props:姿势(PosePickerProps)与手势(GestureOption 组装)
+ * 都结构满足——key 放宽为 string,标题可覆盖(手势框传「选择左手势」)。
+ */
+export type PickerFrameOption = {
+    key: string;
+    label: string;
+    disabled?: boolean;
+    hint?: string;
+    /** 缩略图 URL(2026-10-05):任一选项带图则整框切两列网格卡片 */
+    thumbUrl?: string;
+};
+export type PickerFrameProps = {
+    options: PickerFrameOption[];
+    current: string;
+    onPick: (key: string) => void;
+    onClose: () => void;
+    /** 标题覆盖;缺省「姿势来源」 */
+    title?: string;
+};
+export declare function PosePickerFrame({ options, current, onPick, onClose, title, }: PickerFrameProps): React.ReactElement;
+export default PosePickerFrame;
+//# sourceMappingURL=PosePickerFrame.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PosePickerFrame.d.ts","sourceRoot":"","sources":["../../src/poseMode/PosePickerFrame.tsx"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AAIzB;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,iBAAiB,EAAE,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,wBAAgB,eAAe,CAAC,EAC9B,OAAO,EACP,OAAO,EACP,MAAM,EACN,OAAO,EACP,KAAK,GACN,EAAE,gBAAgB,GAAG,KAAK,CAAC,YAAY,CA4NvC;AAED,eAAe,eAAe,CAAA"}