@dreamerbird/camera-studio 0.0.0-stage → 0.1.0

package/dist/PlacementManager.js

@@ -0,0 +1,1525 @@
+import { editable as e } from '@dreamerbird/r3f';
+import { getStudioSync, onChange, types as t, val } from '@dreamerbird/core';
+import { privateAPI } from '@dreamerbird/core/privateAPIs';
+import { useVal } from '@dreamerbird/react';
+import { translate } from '@dreamerbird/studio/i18n';
+// 内部 Studio 通道:删除合并事务需要 stateEditors.forgetObject
+// (按地址清持久数据,不要求对象已挂载)——与 keyframeTracks 同先例
+import getStudio from '@dreamerbird/studio/getStudio';
+import { TransformControls, useFBX } from '@react-three/drei';
+import { useFrame, useThree } from '@react-three/fiber';
+import React, { Suspense, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { AnimationMixer, Box3, BoxGeometry, Mesh, MeshBasicMaterial, Raycaster, Vector3, } from 'three';
+import { SkeletonUtils } from 'three-stdlib';
+import { registerBoneAnchors, unregisterBoneAnchors } from './boneAnchors';
+import { notifyTargetRegistryChange, sheetObjectExists } from './aimTargets';
+import { createGLTFLoader } from './assetLibrary/gltfLoader';
+import { getLibrary } from './assetLibrary/library';
+import { LibraryError } from './assetLibrary/source';
+import { entryOptions } from './assetLibrary/options';
+import { computeDropPoint } from './dropPoint';
+import { registerEditorOnly } from './editorOnly';
+import { createSelectionOutlineRenderer, } from './selectionOutline';
+import { useModalGrab } from './modalGrab';
+import { disposeObjectTree } from './assetLibrary/dispose';
+import { applyPose, captureBindPose } from './assetLibrary/pose';
+import { isPoseEntryUsed, posePropConfigShape, shouldApplyPoseDuringPlayback, shouldApplyPoseWhenIdle, } from './placementPoseProps';
+import { PoseModeRig } from './poseMode/PoseModeRig';
+import { PoseModeBar } from './poseMode/PoseModeBar';
+import { enterPoseSession, getPoseSession, noteModelDoubleClick, usePoseSessionKey, } from './poseMode/poseSession';
+import { resolveControlSpec } from './poseMode/controlSpec';
+import { prefetchLibPoses, resolvePoseBones } from './poseMode/poseLibResolve';
+import { collectLibPoseIdsForProps, getPoseTrackId, getTrackIdForProp, } from './poseMode/poseTrack';
+import { gesturePropConfigShape, resolveGestureBones } from './gestureProps';
+import { computeLegacyPoseMigration } from './poseMode/poseMigration';
+import { parsePoseValue } from './poseMode/poseValue';
+import { formatSceneObjectId } from './agent/objectIds';
+import { registerSceneSheetObject, unregisterSceneSheetObject, } from './agent/runtime/objectRuntime';
+import { createPlacementWaiter, rejectPlacement, resolvePlacementPersisted, } from './agent/runtime/placementLifecycle';
+import { clearAnimationLoadStatus, setAnimationLoadStatus, } from './agent/runtime/animationStatus';
+/** 注册表对象的 theatre key(大纲顶层 "Placements" 行;Agent resolver 只读探测用) */
+export const PLACEMENTS_REGISTRY_KEY = 'Placements';
+function assetStorageOf(project) {
+    const internal = privateAPI(project);
+    return internal?.assetStorage;
+}
+/**
+ * 每个资产 id 的 file 属性配置,模块级缓存。
+ * t.file/t.number 每次调用都会生成新的闭包(interpolate 等),而 sheet.object
+ * 对同一个 key 的重复调用要求配置 fast-deep-equal(函数按引用比)——
+ * 只有缓存成同一个对象引用,命令式创建和 <e.group additionalProps>
+ * 两条路径的配置才能相等。
+ */
+const fileConfigCache = new Map();
+/**
+ * 动作/姿势下拉配置,按 (属性, 模型库条目 id) 缓存。
+ * 和上面 fileConfigCache 同一个原因:sheet.object 对同一 key 的重复调用
+ * 要求配置 fast-deep-equal(函数按引用比),所以闭包不能每次新建。
+ * 选项函数本身不闭包骨架族,而是闭包模型条目 id,调用时才从库快照解析
+ * rig——配置从首次渲染起引用稳定,快照就绪后筛选自动生效。
+ */
+const literalConfigCache = new Map();
+function literalConfigFor(kind, modelEntryId) {
+    const cacheKey = `${kind}:${modelEntryId ?? ''}`;
+    let config = literalConfigCache.get(cacheKey);
+    if (!config) {
+        config = t.stringLiteral('', () => entryOptions(getLibrary().getEntriesSnapshot(), kind, modelEntryId), 
+        // label 用函数形式:studio 每次渲染现调(resolvePropLabel),
+        // 语言切换热改;箭头在缓存首次创建时定义,引用稳定
+        {
+            label: () => translate('pg.props.animation'),
+            as: 'menu',
+        });
+        literalConfigCache.set(cacheKey, config);
+    }
+    return config;
+}
+/** 已放置模型的 theatre 对象 → {PlacementEntry, 场景实例} 映射,
+ * App 通过 selection 反查 rig,Task 6 用 instance 抽帧。
+ */
+const placementObjects = new Map();
+export function getPlacementEntryForObject(obj) {
+    return placementObjects.get(obj)?.entry;
+}
+/** 按 theatre 对象取已放置实例的 entry 与场景 Group,供 App 抽帧/查 rig 用 */
+export function getPlacementInstanceForObject(obj) {
+    return placementObjects.get(obj);
+}
+/** 统计场景里引用某库条目的已放置实例数(模型本体/动作/姿势三种引用) */
+export function countLibraryEntryUsage(entryId) {
+    let n = 0;
+    for (const [obj, { entry }] of placementObjects.entries()) {
+        if (entry.libraryEntryId === entryId)
+            n++;
+        if (val(obj.props.animation) === entryId)
+            n++;
+        if (isPoseEntryUsed(val(obj.props.pose) ?? '', entryId))
+            n++;
+    }
+    return n;
+}
+function fileConfigFor(assetId) {
+    let config = fileConfigCache.get(assetId);
+    if (!config) {
+        // label 函数形式:面板每次渲染现调,语言切换热改(对齐
+        // literalConfigFor);缓存在首次创建时固化引用,满足 deep-equal
+        config = t.file(assetId, {
+            label: () => translate('pg.props.source'),
+        });
+        fileConfigCache.set(assetId, config);
+    }
+    return config;
+}
+function getRegistry(sheet) {
+    // 注册表只是存数据的对象,不出现在大纲树
+    return sheet.object(PLACEMENTS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+}
+/**
+ * 放置时射线检测的目标清单(模块级登记表)。
+ * 只有登记过的分组才参与落点检测——ghost 本身、星星、gizmo、相机子树
+ * 都不在表里,检测时直接跳过,不用测完再过滤。模型面数越高省得越多。
+ * 想让人能把模型摞在已有模型上,就把对应分组登记进来。
+ */
+const placementSurfaces = new Set();
+/** 把 ref 指向的分组登记为落点表面,卸载时自动移除 */
+export function usePlacementSurface(ref) {
+    useEffect(() => {
+        const obj = ref.current;
+        if (!obj)
+            return;
+        placementSurfaces.add(obj);
+        return () => {
+            placementSurfaces.delete(obj);
+        };
+    }, [ref]);
+}
+/** 落点表面登记表的只读视图(路径预设落点标记也用这套射线目标) */
+export function getPlacementSurfaces() {
+    return placementSurfaces;
+}
+/**
+ * 「放置的模型」子集:placementSurfaces 里属于库放置实例的根(背景
+ * 场景模型不在此列)。路径预设拖拽吸附用——拖到放置的模型上对到它的
+ * 中心,拖到背景/地面保持精确落点
+ */
+const placedModelRoots = new Set();
+/** 放置实例登记自己的场景根,卸载时自动移除 */
+function usePlacedModelRoot(ref) {
+    useEffect(() => {
+        const obj = ref.current;
+        if (!obj)
+            return;
+        placedModelRoots.add(obj);
+        return () => {
+            placedModelRoots.delete(obj);
+        };
+    }, [ref]);
+}
+/** 放置模型根集合的只读视图 */
+export function getPlacedModelRoots() {
+    return placedModelRoots;
+}
+/** 放置实例登记表:placementKey → 场景实例根(父级绑定的 model: 解析用) */
+const placedInstances = new Map();
+/**
+ * 登记/注销放置实例并广播目标登记表变更:持久化的瞄准/父级绑定在
+ * 异步实例(模型加载)挂载瞬间即可解析,ShotCamera/Anchors 无需等
+ * 无关重渲染(对齐 registerAnchorObject 的广播语义;注销同理——
+ * 被瞄准的模型删除后 tracking/看护立即回退,不卡死)。usePlacedInstance
+ * 的 hook 语义拆成命令式对,测试可直接断言广播。
+ */
+export function registerPlacedInstance(key, instance) {
+    placedInstances.set(key, instance);
+    notifyTargetRegistryChange();
+}
+export function unregisterPlacedInstance(key) {
+    placedInstances.delete(key);
+    notifyTargetRegistryChange();
+}
+/** 放置实例登记/注销的便利 hook(PlacedModelCore 用) */
+function usePlacedInstance(key, instance) {
+    useEffect(() => {
+        if (!instance)
+            return;
+        registerPlacedInstance(key, instance);
+        return () => {
+            unregisterPlacedInstance(key);
+        };
+    }, [key, instance]);
+}
+export function getPlacedInstances() {
+    return placedInstances;
+}
+const selectionGizmoTargets = new Map();
+/**
+ * 登记表变更通知:SelectionGizmo 只在选中变化时重算附着目标,
+ * 但"登记被注销"也要立刻反映(比如路径驱动启用时,正选中的相机
+ * 箭头要马上收起来)——登记/注销都通过这里广播
+ */
+const gizmoRegistryListeners = new Set();
+/** 订阅登记表变更,返回退订函数 */
+export function onGizmoRegistryChange(listener) {
+    gizmoRegistryListeners.add(listener);
+    return () => {
+        gizmoRegistryListeners.delete(listener);
+    };
+}
+function notifyGizmoRegistryChange() {
+    gizmoRegistryListeners.forEach((l) => l());
+}
+/** 查某个 theatre 对象的登记项(SelectionGizmo 取附着目标用) */
+export function getGizmoTargetEntry(obj) {
+    return selectionGizmoTargets.get(obj);
+}
+/** 登记/注销选中 gizmo 目标;boxHighlight 默认开,返回注销函数 */
+export function registerGizmoTarget(obj, node, opts) {
+    selectionGizmoTargets.set(obj, {
+        node,
+        boxHighlight: opts?.boxHighlight ?? true,
+    });
+    notifyGizmoRegistryChange();
+    return () => {
+        selectionGizmoTargets.delete(obj);
+        notifyGizmoRegistryChange();
+    };
+}
+/**
+ * 把 ref 指向的节点登记为选中 gizmo 的附着目标,卸载时自动移除。
+ * enabled=false 时不登记:驱动被路径接管的对象(沿路径的相机/瞄准点)
+ * 拖了也不生效,箭头干脆不出现(对齐 Blender 约束激活时物体拖不动)
+ */
+export function useSelectionGizmoTarget(objRef, nodeRef, enabled = true, opts) {
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const obj = objRef.current;
+        const node = nodeRef.current;
+        if (!obj || !node)
+            return;
+        return registerGizmoTarget(obj, node, opts);
+        // 两个 ref 都是挂载后不再变的;enabled 翻转时注销/重新登记
+    }, [enabled]);
+}
+/**
+ * 点 gizmo 箭头时射线会穿过箭头打到后面的模型,松手那一下会被误当成
+ * "点击选中别的模型"。拖 gizmo 期间和松手后一小段时间内,点选一律忽略。
+ */
+let suppressSelectUntil = 0;
+/** 当前这次点击是否该被 gizmo 吞掉(场景里所有点选入口共用一个判断) */
+export function isSelectSuppressed() {
+    return performance.now() < suppressSelectUntil;
+}
+/** 拖 gizmo 期间/松手后短暂屏蔽场景点选(路径控制点的手柄也在用) */
+export function suppressSelectBriefly() {
+    suppressSelectUntil = performance.now() + 200;
+}
+/** 解析放置清单 JSON;坏数据一律回退空(注册表是底账,勿手改)。
+ *  导出给 Agent resolver:无副作用查询在注册表对象已存在时复用同一解析 */
+export function readRegistry(registry) {
+    try {
+        const list = JSON.parse(registry.value.list);
+        return Array.isArray(list) ? list : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** 所有已放置模型的落点(给 findFreeSpot 算默认位用) */
+export function readPlacementPositions(sheet) {
+    return readRegistry(getRegistry(sheet)).map((e) => e.position);
+}
+/** 读放置清单全部 entry(App 判右键对象是否库来源用)。registry 对象由
+ *  PlacedModels 挂载时已创建,同 key 同配置的 sheet.object 是安全的重复调用 */
+export function readPlacementEntries(sheet) {
+    return readRegistry(getRegistry(sheet));
+}
+/**
+ * 放置模型的 theatreKey:顶层扁平化(不再套 "Models /" 文件夹),名字取自
+ * 文件名(去扩展名,不安全字符换下划线)。撞名才追加 -2/-3 序号,平时保持
+ * 干净(theatreKey 必须唯一,同名模型放两次需要区分)。防撞查两处:放置
+ * 清单(注册表已写、对象尚未挂载的空窗) + 全场景路径探测(顶层名字可能与
+ * 相机/灯光/演示模型撞,如 "Camera.fbx"、"Thingy.fbx",只查不建)
+ */
+export function uniquePlacedModelKey(sheet, label) {
+    const base = label.replace(/\.[^.]+$/, '').replace(/[^\w-]/g, '_') || 'model';
+    let taken;
+    try {
+        taken = new Set(readPlacementEntries(sheet).map((e) => e.key));
+    }
+    catch {
+        // 注册表对象尚未创建(理论外场景):按空清单处理,探测兜底防重
+        taken = new Set();
+    }
+    let key = base;
+    for (let i = 2; taken.has(key) || sheetObjectExists(sheet, key); i++) {
+        key = `${base}-${i}`;
+    }
+    return key;
+}
+/**
+ * 等资产存储就绪:attach 完成前 project.assetStorage 还是占位实现,
+ * getAssetUrl 只会返回 "undefined/<id>" 假地址(theatre 官方也要求
+ * project.ready 之后再取资产地址)。就绪前渲染已放置模型必然 404。
+ */
+function useProjectReady(project) {
+    const [ready, setReady] = useState(() => project.isReady);
+    useEffect(() => {
+        if (ready)
+            return;
+        let cancelled = false;
+        void project.ready.then(() => {
+            if (!cancelled)
+                setReady(true);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [project, ready]);
+    return ready;
+}
+/** 响应式读放置清单:scrub 提交/撤销/同步都会触发 onValuesChange */
+function usePlacementsList(sheet) {
+    const registry = useMemo(() => getRegistry(sheet), [sheet]);
+    const [list, setList] = useState(() => readRegistry(registry));
+    useEffect(() => {
+        setList(readRegistry(registry));
+        return registry.onValuesChange(() => setList(readRegistry(registry)));
+    }, [registry]);
+    return list;
+}
+/** 归一化:任意 FBX 单位差异很大,统一缩放到最大边 5 个世界单位,底部对齐落点 */
+function useNormalizedModel(fbx) {
+    return useMemo(() => {
+        const box = new Box3().setFromObject(fbx);
+        const size = box.getSize(new Vector3());
+        const maxDim = Math.max(size.x, size.y, size.z);
+        return {
+            scale: maxDim > 0 ? 5 / maxDim : 1,
+            // lift 是模型局部单位,放进 scale 过的组里后底部正好落在 y=0
+            lift: -box.min.y,
+        };
+    }, [fbx]);
+}
+/** ghost:克隆一份(SkinnedMesh 安全),材质全部换成半透明 */
+function makeGhost(fbx) {
+    const ghost = SkeletonUtils.clone(fbx);
+    ghost.traverse((obj) => {
+        const mesh = obj;
+        if (!mesh.isMesh)
+            return;
+        const materials = Array.isArray(mesh.material)
+            ? mesh.material
+            : [mesh.material];
+        const ghosted = materials.map((m) => {
+            const c = m.clone();
+            c.transparent = true;
+            c.opacity = 0.4;
+            c.depthWrite = false;
+            return c;
+        });
+        mesh.material = Array.isArray(mesh.material) ? ghosted : ghosted[0];
+    });
+    return ghost;
+}
+/**
+ * 放置状态的控制器:选文件 → 存资产 + 进放置模式;确认 → 先放入 pending
+ * (模型立刻渲染),持久化由 PlacedModel 挂载后一次性提交(清单 + source
+ * 静态覆盖同一个 scrub,一步撤销);取消/确认后释放 blob URL。
+ */
+export function usePlacementController(project, sheet) {
+    const [placing, setPlacing] = useState(null);
+    const [pendingEntry, setPendingEntry] = useState(null);
+    const startPlacing = useCallback(async (file) => {
+        // 等 attach 完成:占位存储的 createAsset 会直接抛错
+        await project.ready;
+        const storage = assetStorageOf(project);
+        if (!storage) {
+            console.warn('[placement] 没有 studio 资产存储,无法放置');
+            return;
+        }
+        // 重名且内容不同时 createAsset 会弹窗让用户改名;返回 null 即用户取消或失败
+        let assetId = null;
+        try {
+            assetId = await storage.createAsset(file);
+        }
+        catch (err) {
+            console.warn('[placement] 创建资产失败', err);
+            return;
+        }
+        if (!assetId)
+            return;
+        setPlacing({
+            url: URL.createObjectURL(file),
+            label: file.name,
+            source: { type: 'local', file, assetId },
+        });
+    }, [project]);
+    /** 从资产库选模型进入放置模式:不创建 theatre 项目资产 */
+    const libraryGenRef = useRef(0);
+    const startPlacingFromLibrary = useCallback(async (entry) => {
+        const gen = ++libraryGenRef.current;
+        const url = await getLibrary().getBlobUrl(entry.blobId);
+        // 用户快速切换选择时,旧加载结果直接丢弃
+        if (gen !== libraryGenRef.current)
+            return;
+        setPlacing({
+            url,
+            label: entry.name,
+            source: { type: 'library', entryId: entry.id },
+        });
+    }, []);
+    const cancelPlacing = useCallback(() => {
+        setPlacing((p) => {
+            // 本地文件是自己创建的 blob URL,库 URL 由 backend 管理生命周期
+            if (p && p.source.type === 'local')
+                URL.revokeObjectURL(p.url);
+            return null;
+        });
+    }, []);
+    const confirmPlacing = useCallback((point) => {
+        if (!placing)
+            return;
+        const key = uniquePlacedModelKey(sheet, placing.label);
+        if (placing.source.type === 'local') {
+            setPendingEntry({
+                key,
+                assetId: placing.source.assetId,
+                position: point,
+                pending: true,
+            });
+        }
+        else {
+            setPendingEntry({
+                key,
+                libraryEntryId: placing.source.entryId,
+                position: point,
+                pending: true,
+            });
+        }
+        if (placing.source.type === 'local')
+            URL.revokeObjectURL(placing.url);
+        setPlacing(null);
+    }, [placing, sheet]);
+    /**
+     * 点击库卡片直接落点:跳过幽灵预览,走与 confirmPlacing 相同的落地管线。
+     * 返回 {key, persisted}(2026-10-17,Task 8):Agent models.create 靠
+     * persisted 等挂载完成(completion:mounted);waiter 必须先于
+     * setPendingEntry 创建,挂载链路的 resolve/reject 都按 key 找它。
+     * UI 调用方不 await persisted —— 这里挂 noop catch 兜底,失败告警由
+     * PlacedModelErrorBoundary 负责,不产生 unhandled rejection。
+     */
+    const placeLibraryEntryAt = useCallback((entry, point) => {
+        const key = uniquePlacedModelKey(sheet, entry.name);
+        const persisted = createPlacementWaiter(key);
+        persisted.catch(() => { });
+        setPendingEntry({
+            key,
+            libraryEntryId: entry.id,
+            position: point,
+            pending: true,
+        });
+        return { key, persisted };
+    }, [sheet]);
+    const clearPending = useCallback(() => setPendingEntry(null), []);
+    return {
+        placing,
+        pendingEntry,
+        startPlacing,
+        startPlacingFromLibrary,
+        cancelPlacing,
+        confirmPlacing,
+        placeLibraryEntryAt,
+        clearPending,
+    };
+}
+/**
+ * 放置模式下的 Canvas 内容:半透明 ghost 跟随光标。
+ * 事件走 canvas 的 DOM 监听 + 手动射线检测,不用不可见网格接事件——
+ * 视线与地面平行时网格永远打不中,事件根本不触发,看起来就是"没反应"。
+ * 落点规则:物体表面优先;y=0 地面(数学平面,无限大)兜底;视线与地面
+ * 平行或朝天时再退到"前方 30 个单位、压到地面",保证任何视角都有落点预览。
+ */
+export function PlacementRig(props) {
+    return props.placing.source.type === 'local' ? (React.createElement(PlacementRigFBX, { ...props })) : (React.createElement(PlacementRigGLTF, { ...props }));
+}
+/** 本地 FBX 预览:用 drei 的 useFBX,加载完交给公共的 Rig 逻辑 */
+function PlacementRigFBX({ placing, onConfirm, onCancel, confirmOnPointerUp, }) {
+    const fbx = useFBX(placing.url);
+    return (React.createElement(PlacementRigCore, { model: fbx, onConfirm: onConfirm, onCancel: onCancel, confirmOnPointerUp: confirmOnPointerUp }));
+}
+/** 资产库 GLB 预览:用 GLTFLoader 异步加载,失败时交给错误边界 */
+function PlacementRigGLTF({ placing, onConfirm, onCancel, confirmOnPointerUp, }) {
+    const [model, setModel] = useState(null);
+    const [failed, setFailed] = useState(false);
+    useEffect(() => {
+        let cancelled = false;
+        const loader = createGLTFLoader();
+        loader
+            .loadAsync(placing.url)
+            .then((gltf) => {
+            if (!cancelled)
+                setModel(gltf.scene);
+        })
+            .catch((err) => {
+            console.warn('[placement] 库模型预览加载失败', err);
+            // 资产 URL 不可达/解析失败:上告库 onError 通道(toast 条),
+            // 本地状态照走错误边界取消放置,不崩画布
+            getLibrary().reportError(new LibraryError('network', '库模型预览加载失败', err));
+            if (!cancelled)
+                setFailed(true);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [placing.url]);
+    // 卸载或 URL 变化时释放模型 GPU 资源
+    useEffect(() => {
+        return () => {
+            if (model)
+                disposeObjectTree(model);
+        };
+    }, [model]);
+    if (failed)
+        throw new Error('[placement] 库模型预览加载失败');
+    if (!model)
+        return null;
+    return (React.createElement(PlacementRigCore, { model: model, onConfirm: onConfirm, onCancel: onCancel, confirmOnPointerUp: confirmOnPointerUp }));
+}
+/** 放置模式下的 Canvas 内容:半透明 ghost 跟随光标。
+ * 事件走 canvas 的 DOM 监听 + 手动射线检测,不用不可见网格接事件——
+ * 视线与地面平行时网格永远打不中,事件根本不触发,看起来就是"没反应"。
+ * 落点规则:物体表面优先;y=0 地面(数学平面,无限大)兜底;视线与地面
+ * 平行或朝天时再退到"前方 30 个单位、压到地面",保证任何视角都有落点预览。 */
+function PlacementRigCore({ model, onConfirm, onCancel, confirmOnPointerUp, }) {
+    const invalidate = useThree((s) => s.invalidate);
+    const gl = useThree((s) => s.gl);
+    const camera = useThree((s) => s.camera);
+    const ghost = useMemo(() => makeGhost(model), [model]);
+    const { scale, lift } = useNormalizedModel(model);
+    const ghostRef = useRef(null);
+    const raycaster = useMemo(() => new Raycaster(), []);
+    const computePoint = useCallback((clientX, clientY) => computeDropPoint(raycaster, camera, placementSurfaces, gl.domElement.getBoundingClientRect(), clientX, clientY), [gl, camera, raycaster]);
+    // 鼠标事件只记坐标并申请一帧,真正的落点计算在帧回调里做一次——
+    // pointermove 一秒能来上百次(每次都全量射线检测会很卡),渲染帧一秒最多 60 次
+    const pendingMoveRef = useRef(null);
+    useFrame(() => {
+        const pending = pendingMoveRef.current;
+        if (!pending)
+            return;
+        pendingMoveRef.current = null;
+        const p = computePoint(pending.x, pending.y);
+        if (ghostRef.current) {
+            ghostRef.current.visible = true;
+            ghostRef.current.position.copy(p);
+        }
+    });
+    useEffect(() => {
+        const el = gl.domElement;
+        let downPos = null;
+        const onMove = (ev) => {
+            pendingMoveRef.current = { x: ev.clientX, y: ev.clientY };
+            invalidate();
+        };
+        const onDown = (ev) => {
+            downPos = { x: ev.clientX, y: ev.clientY };
+        };
+        const onClick = (ev) => {
+            if (ev.button !== 0)
+                return;
+            // 拖拽模式下画布点击不确认,确认只走松手
+            if (confirmOnPointerUp)
+                return;
+            // 拖动后的松手不算点击
+            if (downPos &&
+                Math.hypot(ev.clientX - downPos.x, ev.clientY - downPos.y) > 2)
+                return;
+            const p = computePoint(ev.clientX, ev.clientY);
+            // 太远的落点直接忽略,留在放置模式里(防止误放到天边)
+            if (p.distanceTo(camera.position) > 300)
+                return;
+            onConfirm({ x: p.x, y: p.y, z: p.z });
+        };
+        const onKey = (ev) => {
+            if (ev.key === 'Escape')
+                onCancel();
+        };
+        const onContextMenu = (ev) => {
+            ev.preventDefault();
+            onCancel();
+        };
+        el.addEventListener('pointermove', onMove);
+        el.addEventListener('pointerdown', onDown);
+        el.addEventListener('click', onClick);
+        window.addEventListener('keydown', onKey);
+        window.addEventListener('contextmenu', onContextMenu);
+        return () => {
+            el.removeEventListener('pointermove', onMove);
+            el.removeEventListener('pointerdown', onDown);
+            el.removeEventListener('click', onClick);
+            window.removeEventListener('keydown', onKey);
+            window.removeEventListener('contextmenu', onContextMenu);
+        };
+    }, [
+        gl,
+        computePoint,
+        camera,
+        invalidate,
+        onConfirm,
+        onCancel,
+        confirmOnPointerUp,
+    ]);
+    // 拖拽模式:按下发生在面板卡片上,松手才是确认。松手在画布外(面板区域)
+    // = 取消;太远(>300)也取消,防止误放到天边
+    useEffect(() => {
+        if (!confirmOnPointerUp)
+            return;
+        const el = gl.domElement;
+        const onUp = (ev) => {
+            if (ev.button !== 0)
+                return;
+            // 画布铺满全窗口、垫在面板之下:松手在面板/工具栏等 DOM 上时 target 不是画布,
+            // 必须取消(spec:松手在面板区域 = 静默取消)。提示条 pointerEvents:none 不挡
+            if (ev.target !== el) {
+                onCancel();
+                return;
+            }
+            const p = computePoint(ev.clientX, ev.clientY);
+            if (p.distanceTo(camera.position) > 300) {
+                onCancel();
+                return;
+            }
+            onConfirm({ x: p.x, y: p.y, z: p.z });
+        };
+        window.addEventListener('pointerup', onUp);
+        return () => window.removeEventListener('pointerup', onUp);
+    }, [confirmOnPointerUp, gl, camera, computePoint, onConfirm, onCancel]);
+    return (
+    // 首次 pointermove 之前不显示,避免在原地闪一下
+    React.createElement("group", { ref: ghostRef, scale: scale, visible: false },
+        React.createElement("primitive", { object: ghost, position: [0, lift, 0] })));
+}
+/** FBX 解析失败(文件损坏/格式太老)时取消放置,而不是崩掉画布、卡住按钮 */
+export class PlacementRigErrorBoundary extends React.Component {
+    constructor() {
+        super(...arguments);
+        this.state = { failed: false };
+    }
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(err) {
+        console.warn('[placement] 模型文件解析失败,已取消放置', err);
+        this.props.onCancel();
+    }
+    render() {
+        return this.state.failed ? null : this.props.children;
+    }
+}
+/** 已放置的模型们:按清单渲染(外加刚确认、待提交的那条),每个是独立的 theatre 可编辑对象 */
+export function PlacedModels({ sheet, project, pendingEntry, onPersisted, selectLocked, onObjectMenu, }) {
+    const list = usePlacementsList(sheet);
+    const ready = useProjectReady(project);
+    // pending 提交进清单(list)到 clearPending 之间有一瞬两边都渲染,
+    // React 报 duplicate key;已在清单里的 pending 副本直接跳过
+    const entries = pendingEntry && !list.some((e) => e.key === pendingEntry.key)
+        ? [...list, pendingEntry]
+        : list;
+    if (!ready)
+        return null;
+    return (React.createElement(React.Fragment, null, entries.map((entry) => (React.createElement(Suspense, { key: entry.key, fallback: null },
+        React.createElement(PlacedModelErrorBoundary, { entry: entry, project: project, sheet: sheet, onPersisted: onPersisted, selectLocked: selectLocked, onObjectMenu: onObjectMenu }))))));
+}
+function PlacedModel({ entry, project, sheet, onPersisted, selectLocked, onObjectMenu, }) {
+    if (entry.libraryEntryId) {
+        return (React.createElement(LibraryPlacedModel, { entry: entry, project: project, sheet: sheet, onPersisted: onPersisted, selectLocked: selectLocked, onObjectMenu: onObjectMenu }));
+    }
+    return (React.createElement(FBXPlacedModel, { entry: entry, project: project, sheet: sheet, onPersisted: onPersisted, selectLocked: selectLocked, onObjectMenu: onObjectMenu }));
+}
+/** 旧本地 FBX 路径:通过 theatre assetStorage 取 URL,再用 useFBX 加载 */
+function FBXPlacedModel({ entry, project, sheet, onPersisted, selectLocked, onObjectMenu, }) {
+    const url = useMemo(() => {
+        const storage = assetStorageOf(project);
+        if (!storage || !entry.assetId)
+            throw new Error('asset storage unavailable');
+        return storage.getAssetUrl(entry.assetId);
+    }, [project, entry.assetId]);
+    const fbx = useFBX(url);
+    return (React.createElement(PlacedModelCore, { entry: entry, sheet: sheet, group: fbx, animations: fbx.animations, sourceType: "local", onPersisted: onPersisted, selectLocked: selectLocked, onObjectMenu: onObjectMenu }));
+}
+/**
+ * 库模型加载:条目解析 → blob URL → GLTFLoader。fetch/解析失败统一包成
+ * LibraryError('network') 并经库的 onError 通道上告(宿主错误条提示),
+ * 条目缺失是数据问题报 not-found;两种都继续抛给调用方走错误边界,
+ * 选择框/画布照常。
+ */
+export async function loadLibraryModel(entryId, lib = getLibrary()) {
+    try {
+        const libEntry = await lib.getEntry(entryId);
+        if (!libEntry || libEntry.kind !== 'model') {
+            throw new LibraryError('not-found', `库模型条目不存在: ${entryId}`);
+        }
+        const url = await lib.getBlobUrl(libEntry.blobId);
+        const gltf = await createGLTFLoader().loadAsync(url);
+        return { group: gltf.scene, animations: gltf.animations };
+    }
+    catch (err) {
+        const wrapped = err instanceof LibraryError
+            ? err
+            : new LibraryError('network', `库模型加载失败: ${entryId}`, err);
+        lib.reportError(wrapped);
+        throw wrapped;
+    }
+}
+/** 资产库 GLB 路径:解析条目、取 blob URL、用 GLTFLoader 异步加载 */
+function LibraryPlacedModel({ entry, project, sheet, onPersisted, selectLocked, onObjectMenu, }) {
+    const [loaded, setLoaded] = useState(null);
+    const [failed, setFailed] = useState(false);
+    useEffect(() => {
+        let cancelled = false;
+        loadLibraryModel(entry.libraryEntryId)
+            .then((result) => {
+            if (!cancelled)
+                setLoaded(result);
+        })
+            .catch((err) => {
+            console.warn('[placement] 库模型加载失败', err);
+            if (!cancelled)
+                setFailed(true);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [entry.libraryEntryId]);
+    // 卸载或条目变化时释放已加载模型
+    useEffect(() => {
+        return () => {
+            if (loaded?.group)
+                disposeObjectTree(loaded.group);
+        };
+    }, [loaded?.group]);
+    if (failed)
+        throw new Error('[placement] 库模型加载失败');
+    if (!loaded)
+        return null;
+    return (React.createElement(PlacedModelCore, { entry: entry, sheet: sheet, group: loaded.group, animations: loaded.animations, sourceType: "library", onPersisted: onPersisted, selectLocked: selectLocked, onObjectMenu: onObjectMenu }));
+}
+/** 已加载 Group 之后的公共逻辑:克隆、归一化、动画 mixer、点选菜单、持久化 */
+function PlacedModelCore({ entry, sheet, group, animations, sourceType, onPersisted, selectLocked, onObjectMenu, }) {
+    const additionalProps = useMemo(() => {
+        const modelEntryId = sourceType === 'library' ? entry.libraryEntryId : undefined;
+        const props = {
+            animation: literalConfigFor('animation', modelEntryId),
+            // 姿势 = 时间轴单属性(spec §6.1 + 2026-10-01 属性行化):值
+            // JSON(lib 引用|custom 快照),面板显示为属性行,值区域走注册表
+            // 的 pose 编辑器(弹框选预设);自定义插值器让它可打帧且平滑混合
+            pose: t.string('', posePropConfigShape().opts),
+            // 手势(2026-10-05):姿势的纯选择叠加层,左右手各一行;值是库手势
+            // 引用(或 ''=无手势),应用只写本侧手指骨,可打帧(同姿势插值器)
+            gestureL: t.string('', gesturePropConfigShape('left').opts),
+            gestureR: t.string('', gesturePropConfigShape('right').opts),
+            // 迁移过渡(spec §9):读取/清理旧值用,面板隐藏;下个大版本删 key
+            poseOverride: t.string('', {
+                label: () => translate('pg.props.poseOverride'),
+                hidden: true,
+            }),
+        };
+        if (sourceType === 'local' && entry.assetId) {
+            props.source = fileConfigFor(entry.assetId);
+        }
+        return props;
+    }, [sourceType, entry.assetId, entry.libraryEntryId]);
+    const { scale, lift } = useNormalizedModel(group);
+    const objRef = useRef(undefined);
+    const [sheetObject, setSheetObject] = useState(undefined);
+    // Agent 运行时登记(2026-10-17,Task 8):objRef 填充即「运行时 SheetObject
+    // 已挂载」信号,models.create 的 resolver 复核与 scene/objects 查询都读
+    // 这份登记;清空/卸载时按 id + 同一对象清理,防过期 cleanup 误删新代次
+    const setObjRef = useCallback((obj) => {
+        const id = formatSceneObjectId('model', entry.key);
+        const prev = objRef.current;
+        objRef.current = obj ?? undefined;
+        setSheetObject(obj ?? undefined);
+        if (obj) {
+            registerSceneSheetObject(id, obj);
+        }
+        else {
+            unregisterSceneSheetObject(id, prev);
+        }
+    }, [entry.key]);
+    // 登记为落点表面:之后的放置可以把模型摞到这个模型上
+    const groupRef = useRef(null);
+    usePlacementSurface(groupRef);
+    // 同时登记进「放置的模型」子集:路径拖拽吸附只认放置实例,不认背景
+    usePlacedModelRoot(groupRef);
+    // 登记为选中 gizmo 的附着目标:被选中时身上挂三轴移动箭头
+    useSelectionGizmoTarget(objRef, groupRef);
+    const invalidate = useThree((s) => s.invalidate);
+    // 主画面点选:和 App 里 Model 的 selectThingy 同款。放置模式下点击是
+    // 确认落点,不选中、不拦截;点 gizmo 箭头穿透过来的误点也要吞掉。
+    const selectSelf = (event) => {
+        if (selectLocked || isSelectSuppressed())
+            return;
+        // 摆姿势期间单击(自己或别的模型)都不改选中;stopPropagation 保持
+        // "点击被模型处理"的语义,onPointerMissed 不会触发
+        if (getPoseSession()) {
+            event.stopPropagation();
+            return;
+        }
+        event.stopPropagation();
+        const studio = getStudioSync();
+        if (studio && objRef.current) {
+            studio.setSelection([objRef.current]);
+        }
+    };
+    // 右键:选中自己 + 弹操作菜单(切换手柄模式/删除)。
+    // 放置模式下右键是取消放置(PlacementRig 的监听),这里不抢。
+    const openMenu = (event) => {
+        if (selectLocked || !onObjectMenu)
+            return;
+        event.stopPropagation();
+        event.nativeEvent.preventDefault();
+        const studio = getStudioSync();
+        if (studio && objRef.current) {
+            studio.setSelection([objRef.current]);
+        }
+        onObjectMenu(entry.key, event.nativeEvent.clientX, event.nativeEvent.clientY);
+    };
+    // 双击已选中的人形模型进入姿势模式。第一件事记录 timeStamp:
+    // App 的"双击空白退出"靠它区分落在模型上的双击。
+    const enterPoseViaDoubleClick = (event) => {
+        noteModelDoubleClick(event.nativeEvent.timeStamp);
+        if (selectLocked || isSelectSuppressed())
+            return;
+        const studio = getStudioSync();
+        if (!studio || !objRef.current)
+            return;
+        // 未选中不进:双击的第一击已由 selectSelf 选中,第二击这里自然满足
+        if (!studio.selection.includes(objRef.current))
+            return;
+        if (!resolveControlSpec(instance))
+            return; // 骨架不支持:静默不进
+        event.stopPropagation();
+        enterPoseSession(entry.key);
+    };
+    // 骨架动画:加载结果按 URL 缓存,同一文件放多个会共享同一份骨架,
+    // 互相打架(多个 <primitive> 挂同一个 Object3D 也只有最后一个能显示)。
+    // 所以每个实例克隆一份(SkinnedMesh 安全),配独立的 AnimationMixer。
+    const instance = useMemo(() => SkeletonUtils.clone(group), [group]);
+    const mixer = useMemo(() => new AnimationMixer(instance), [instance]);
+    // 登记进 placedInstances 表:锚点父级绑定的 model: 解析用
+    usePlacedInstance(entry.key, instance);
+    const bindPoseRef = useRef({});
+    // 实例刚克隆出来时同步捕获绑定姿势,确保后续姿势应用 effect 运行前已就位
+    useLayoutEffect(() => {
+        bindPoseRef.current = captureBindPose(instance);
+    }, [instance]);
+    const animationId = useVal(sheetObject?.props.animation) ?? '';
+    const poseJson = useVal(sheetObject?.props.pose) ?? '';
+    const gestureLJson = useVal(sheetObject?.props.gestureL) ?? '';
+    const gestureRJson = useVal(sheetObject?.props.gestureR) ?? '';
+    const poseSessionKey = usePoseSessionKey();
+    // 本模型正处于姿势模式会话:期间骨骼归 IK 骨架每帧重解算
+    const poseModeActive = poseSessionKey === entry.key;
+    const [clip, setClip] = useState(null);
+    const currentActionRef = useRef(null);
+    const pendingUncachesRef = useRef([]);
+    // 登记当前 theatre 对象与 PlacementEntry 的映射,App 用 selection 反查 rig;
+    // 同时保留场景实例,供资产库面板统计引用与 Task 6 抽帧。
+    // 骨骼锚点:按实例骨架登记头/胸口/双手/双腿(运行时,非 theatre 对象),
+    // 登记/注销都广播目标登记表——持久化的瞄准/父级绑定在模型加载完、
+    // 或模型被删的瞬间立即生效/回退,ShotCamera 与 Anchors 订阅见各自组件。
+    // deps 只挂 entry.key:注册表 list 任何增删都会 parse 出全新 entry 身份,
+    // 挂 entry 本体等于"增删任一模型重建全部骨骼锚点节点",已绑在骨骼锚点
+    // 上的锚点网格会随之脱离场景树;entry 内容放置后不可变,同 key 内容恒等。
+    useEffect(() => {
+        if (!sheetObject)
+            return;
+        placementObjects.set(sheetObject, { entry, instance });
+        registerBoneAnchors(entry.key, instance);
+        notifyTargetRegistryChange();
+        return () => {
+            placementObjects.delete(sheetObject);
+            unregisterBoneAnchors(entry.key);
+            notifyTargetRegistryChange();
+        };
+    }, [sheetObject, entry.key, instance]);
+    // animation 属性变化时加载库动画 GLB。加载状态登记进
+    // agent/runtime/animationStatus(animations.getStatus 的唯一数据源,
+    // 不从 props 猜测):开始=loaded:false、成功=loaded:true、失败=error;
+    // cleanup(卸载或 animationId 切换)必须删 key,不留陈旧 loaded。
+    useEffect(() => {
+        if (!animationId) {
+            setClip(null);
+            return;
+        }
+        let cancelled = false;
+        setAnimationLoadStatus(entry.key, { assetId: animationId, loaded: false });
+        const load = async () => {
+            const animEntry = await getLibrary().getEntry(animationId);
+            if (!animEntry || animEntry.kind !== 'animation') {
+                if (!cancelled) {
+                    setClip(null);
+                    setAnimationLoadStatus(entry.key, {
+                        assetId: animationId,
+                        loaded: false,
+                        error: {
+                            code: 'RESOURCE_LOAD_FAILED',
+                            message: `动画资产不存在或类型不符: ${animationId}`,
+                            retryable: false,
+                        },
+                    });
+                }
+                return;
+            }
+            const url = await getLibrary().getBlobUrl(animEntry.blobId);
+            const gltf = await createGLTFLoader().loadAsync(url);
+            if (!cancelled) {
+                setClip(gltf.animations[0] ?? null);
+                setAnimationLoadStatus(entry.key, { assetId: animationId, loaded: true });
+            }
+        };
+        load().catch((err) => {
+            console.warn('[placement] 动画加载失败', err);
+            if (!cancelled) {
+                setClip(null);
+                setAnimationLoadStatus(entry.key, {
+                    assetId: animationId,
+                    loaded: false,
+                    error: {
+                        code: 'RESOURCE_LOAD_FAILED',
+                        message: err instanceof Error ? err.message : String(err),
+                        retryable: true,
+                    },
+                });
+            }
+        });
+        return () => {
+            cancelled = true;
+            clearAnimationLoadStatus(entry.key);
+        };
+    }, [animationId, entry.key]);
+    const [libResolveTick, setLibResolveTick] = useState(0);
+    // 旧两字段 → 新 pose 值迁移(spec §9):一个事务(可撤销、经 saaz 同步),
+    // 幂等——新值已存在或旧值双空即不触发;迁移后旧 override unset 即天然标记
+    useEffect(() => {
+        if (!sheetObject)
+            return;
+        const legacyPose = val(sheetObject.props.pose) ?? '';
+        const legacyOverride = val(sheetObject.props.poseOverride) ?? '';
+        const migrated = computeLegacyPoseMigration({
+            pose: legacyPose,
+            poseOverride: legacyOverride,
+        });
+        // 至多一次(spec §9.2):override 空=天然标记;裸 id 迁移靠「结果与现值相同」
+        // 判定——已迁移过的对象两个开关都假,不再开事务(否则每次挂载重复同值写,
+        // 空撤销步/saaz 噪音)
+        const needsSet = migrated !== null && migrated !== legacyPose;
+        const needsUnset = !!legacyOverride.trim();
+        if (!needsSet && !needsUnset)
+            return;
+        const studio = getStudioSync();
+        if (!studio)
+            return;
+        studio.transaction(({ set, unset }) => {
+            if (needsSet && migrated !== null)
+                set(sheetObject.props.pose, migrated);
+            if (needsUnset)
+                unset(sheetObject.props.poseOverride);
+        });
+    }, [sheetObject]);
+    const poseBones = useMemo(() => resolvePoseBones(parsePoseValue(poseJson)), 
+    // libResolveTick:库引用异步解析到手后 onReady 自增,静止态下逼 memo 重算
+    // (r3f invalidate 只排帧不重渲染 React,spec §5 的「重求值」需要这一跳)
+    [poseJson, libResolveTick]);
+    // 手势层(叠加):本侧手指骨;解析不出 = null(跳过应用,保持姿势层)
+    const gestureLBones = useMemo(() => resolveGestureBones(gestureLJson, 'left'), [gestureLJson, libResolveTick]);
+    const gestureRBones = useMemo(() => resolveGestureBones(gestureRJson, 'right'), [gestureRJson, libResolveTick]);
+    // 库姿势引用预取(spec §5):当前值与轨道全部帧值里的 lib id 异步进缓存,
+    // 到手 invalidate 触发重求值,阶跃变平滑
+    useEffect(() => {
+        if (!sheetObject)
+            return;
+        const ids = collectLibPoseIdsForProps(sheetObject, [
+            'pose',
+            'gestureL',
+            'gestureR',
+        ]);
+        if (ids.length === 0)
+            return;
+        let cancelled = false;
+        prefetchLibPoses(ids, () => {
+            if (cancelled)
+                return;
+            setLibResolveTick((t) => t + 1);
+            invalidate();
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [sheetObject, poseJson, gestureLJson, gestureRJson, invalidate]);
+    // 动画片段切换:0.2s 淡入淡出
+    useEffect(() => {
+        if (!clip) {
+            const oldAction = currentActionRef.current;
+            if (oldAction) {
+                const oldClip = oldAction.getClip();
+                oldAction.fadeOut(0.2);
+                // 淡出结束再 uncache;立即 uncache 会中断淡出插值、骨骼瞬间回弹
+                pendingUncachesRef.current.push(setTimeout(() => {
+                    const act = mixer.existingAction(oldClip, instance);
+                    if (act && act.isRunning())
+                        return;
+                    mixer.uncacheAction(oldClip, instance);
+                }, 250));
+                currentActionRef.current = null;
+            }
+            return;
+        }
+        const oldAction = currentActionRef.current;
+        const oldClip = oldAction?.getClip();
+        const action = mixer.clipAction(clip);
+        action.reset().fadeIn(0.2).play();
+        if (oldAction && oldAction !== action) {
+            oldAction.fadeOut(0.2);
+            if (oldClip) {
+                // 同上:等淡出完成再清缓存,避免打断交叉淡化
+                pendingUncachesRef.current.push(setTimeout(() => {
+                    const act = mixer.existingAction(oldClip, instance);
+                    if (act && act.isRunning())
+                        return;
+                    mixer.uncacheAction(oldClip, instance);
+                }, 250));
+            }
+        }
+        currentActionRef.current = action;
+    }, [clip, mixer, instance]);
+    useEffect(() => {
+        return () => {
+            for (const t of pendingUncachesRef.current)
+                clearTimeout(t);
+            pendingUncachesRef.current = [];
+            mixer.stopAllAction();
+            mixer.uncacheRoot(instance);
+            disposeObjectTree(instance);
+        };
+    }, [mixer, instance]);
+    // 只在 theatre 序列播放时驱动动画:编辑/摆姿势时模型保持静止。
+    // demand 帧循环下没有持续帧,播放状态翻成 true 时主动起一帧,
+    // 之后 useFrame 里边播边续帧;暂停的那帧起不再 invalidate,画面静止。
+    // 序列停止时把当前姿势(或绑定姿势)写回骨骼;播放时由 clip effect + useFrame 驱动,
+    // animation 为空时 mixer 不更新,骨骼保持停止前的姿势,无需额外处理。
+    // 旧的 action fadeOut 残余权重在停止后直接由 applyPose 覆盖,不必 stopAllAction。
+    useEffect(() => {
+        return onChange(sheet.sequence.pointer.playing, (playing) => {
+            if (playing) {
+                invalidate();
+            }
+            else {
+                applyPose(instance, poseBones ?? bindPoseRef.current);
+                // 手势叠加层:姿势层整写之后,只补本侧手指骨(顺序不能反)
+                if (gestureLBones)
+                    applyPose(instance, gestureLBones);
+                if (gestureRBones)
+                    applyPose(instance, gestureRBones);
+                invalidate();
+            }
+        });
+    }, [sheet, invalidate, instance, poseBones, gestureLBones, gestureRBones]);
+    // pose 数据变化且当前未播放时立即应用,覆盖 pose 值切换与撤销/重做路径。
+    // poseModeActive 进 deps:姿势模式期间不抢骨骼(IK 骨架每帧重解算,应用了
+    // 也会被压回);会话退出(true→false)时本 effect 重跑,把当前值补刷回骨骼——
+    // 修「会话期间值被弹框/撤销/同步改掉,Esc 后模型停在旧姿势、再点同值因
+    // 值没变不重刷而永久卡死」的脱节。
+    useEffect(() => {
+        if (!shouldApplyPoseWhenIdle(val(sheet.sequence.pointer.playing), poseModeActive))
+            return;
+        applyPose(instance, poseBones ?? bindPoseRef.current);
+        // 手势叠加层:姿势层整写之后,只补本侧手指骨(顺序不能反)
+        if (gestureLBones)
+            applyPose(instance, gestureLBones);
+        if (gestureRBones)
+            applyPose(instance, gestureRBones);
+        invalidate();
+    }, [
+        instance,
+        poseBones,
+        gestureLBones,
+        gestureRBones,
+        invalidate,
+        sheet,
+        poseModeActive,
+    ]);
+    useFrame((_, delta) => {
+        if (!val(sheet.sequence.pointer.playing))
+            return;
+        if (!sheetObject)
+            return;
+        mixer.update(delta);
+        // 有姿势/手势轨道:求值姿势逐骨压过动作片段(spec §7.1);
+        // 每帧重读求值值(拖针/播放求值产物),resolvePoseBones 有 LRU/缓存兜底。
+        // 轨道有无也现场读——两步撤销首帧(撤关键帧→撤空轨)删轨不改求值值,
+        // 缓存的布尔会滞留 true 让播放被绑定姿势盖住(终审 F2)
+        const hasPoseTrack = getPoseTrackId(sheetObject) !== undefined;
+        const hasGestureLTrack = getTrackIdForProp(sheetObject, 'gestureL') !== undefined;
+        const hasGestureRTrack = getTrackIdForProp(sheetObject, 'gestureR') !== undefined;
+        if (shouldApplyPoseDuringPlayback(hasPoseTrack || hasGestureLTrack || hasGestureRTrack)) {
+            if (hasPoseTrack) {
+                const evaluated = val(sheetObject.props.pose) ?? '';
+                applyPose(instance, resolvePoseBones(parsePoseValue(evaluated)) ?? bindPoseRef.current);
+            }
+            // 手势轨道:求值值裁到本侧手指骨压上;无姿势轨道时身体仍归 mixer
+            if (hasGestureLTrack) {
+                const g = resolveGestureBones(val(sheetObject.props.gestureL) ?? '', 'left');
+                if (g)
+                    applyPose(instance, g);
+            }
+            if (hasGestureRTrack) {
+                const g = resolveGestureBones(val(sheetObject.props.gestureR) ?? '', 'right');
+                if (g)
+                    applyPose(instance, g);
+            }
+        }
+        invalidate();
+    });
+    // pending 条目:对象已由 e.group 建好后,一次性提交清单。
+    // 本地来源额外写 source 静态覆盖,让 theatre 项目状态引用到资产(避免被清理);
+    // 库来源不写 source,清单里的 libraryEntryId 足够恢复。
+    const isPending = 'pending' in entry && entry.pending;
+    useEffect(() => {
+        if (!isPending)
+            return;
+        const obj = objRef.current;
+        const studio = getStudioSync();
+        if (obj && studio) {
+            const registry = getRegistry(sheet);
+            const list = readRegistry(registry);
+            // 已在清单里 = 重做/同步/StrictMode 二次触发,不重复提交
+            if (!list.some((e) => e.key === entry.key)) {
+                const scrub = studio.scrub();
+                scrub.capture(({ set }) => {
+                    const { pending: _pending, ...rest } = entry;
+                    set(registry.props.list, JSON.stringify([...list, rest]));
+                    if (sourceType === 'local' && entry.assetId) {
+                        set(obj.props.source, {
+                            type: 'file',
+                            id: entry.assetId,
+                        });
+                    }
+                });
+                scrub.commit();
+                onPersisted();
+                // Agent models.create 的 mounted 信号(Task 8):注册表提交 +
+                // pending 清理之后才兑现;waiter 不存在(UI 路径)时是 no-op
+                resolvePlacementPersisted(entry.key);
+            }
+        }
+        // pending 条目未持久化即卸载(场景拆解等):拒绝 waiter,Agent 侧
+        // 不悬挂;正常路径 waiter 已 settle 并从 Map 删除,这里是 no-op
+        return () => {
+            rejectPlacement(entry.key, new Error(`[placement] 模型 ${entry.key} 未持久化即卸载`));
+        };
+    }, []);
+    return (React.createElement(e.group, { ref: groupRef, theatreKey: entry.key, objRef: setObjRef, additionalProps: additionalProps, position: [entry.position.x, entry.position.y, entry.position.z], scale: scale, onClick: selectSelf, onContextMenu: openMenu, onDoubleClick: enterPoseViaDoubleClick },
+        React.createElement("primitive", { object: instance, position: [0, lift, 0] }),
+        sheetObject && poseModeActive && (React.createElement(React.Fragment, null,
+            React.createElement(PoseModeRig, { instance: instance, sheetObject: sheetObject, placementKey: entry.key, sheet: sheet }),
+            React.createElement(PoseModeBar, { instance: instance })))));
+}
+/** 本地缺资产(另一个客户端同步来的清单)或 FBX 解析失败时,跳过该模型而不是崩掉画布 */
+class PlacedModelErrorBoundary extends React.Component {
+    constructor() {
+        super(...arguments);
+        this.state = { failed: false };
+    }
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(err) {
+        console.warn(`[placement] 模型 ${this.props.entry.key} 加载失败`, err);
+        // Agent models.create 正等着挂载完成(Task 8):失败必须 reject waiter,
+        // 不能悬挂;UI 路径没有 waiter,rejectPlacement 是 no-op
+        rejectPlacement(this.props.entry.key, err);
+    }
+    render() {
+        return this.state.failed ? null : React.createElement(PlacedModel, { ...this.props });
+    }
+}
+/**
+ * 快捷键切换 gizmo 模式(对齐 Blender):W 选择 / G 移动 / R 旋转 / S 缩放。
+ * 有选中对象时才响应;焦点在输入框时不抢按键(和 studio 快捷键同一套避让)。
+ * G 另有模态抓取(选中对象跟随鼠标,见 SelectionGizmo);W/R/S 只切模式。
+ * 返回 [当前模式, 设置模式]——顶栏模式组和右键菜单都用设置接口切模式。
+ */
+export function useGizmoMode() {
+    const [mode, setMode] = useState('select');
+    useEffect(() => {
+        const onKey = (ev) => {
+            const target = ev.target;
+            if (target &&
+                (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA'))
+                return;
+            // 姿势模式期间 W/E 归 threeIK 操纵器,G/R/S 不响应
+            if (getPoseSession())
+                return;
+            const next = ev.code === 'KeyW'
+                ? 'select'
+                : ev.code === 'KeyG'
+                    ? 'translate'
+                    : ev.code === 'KeyR'
+                        ? 'rotate'
+                        : ev.code === 'KeyS'
+                            ? 'scale'
+                            : null;
+            if (!next)
+                return;
+            const studio = getStudioSync();
+            if (!studio || studio.selection.length === 0)
+                return;
+            setMode(next);
+        };
+        window.addEventListener('keydown', onKey);
+        return () => window.removeEventListener('keydown', onKey);
+    }, []);
+    return [mode, setMode];
+}
+/**
+ * 从放置清单里删除一个模型:单个事务完成 forgetObject + 清单移除 =
+ * 一步撤销(2026-10-19,Task 14 合并;原先只退清单)。
+ * forgetObject 按地址清持久数据(变换/姿势/动画覆盖与轨道,同步到所有
+ * 客户端),撤销一步把清单行和覆盖一起还原;不再残留"同名重放复活旧
+ * 变换"的幽灵数据。theatre 对象本身删不掉(公开 API 没有删除),会留个
+ * 空壳在大纲里,刷新后消失——和撤销放置的已知行为一样。FBX 文件本体
+ * 留在 IndexedDB。
+ */
+export function deletePlacement(sheet, key) {
+    const studio = getStudio();
+    if (!studio)
+        return;
+    const registry = getRegistry(sheet);
+    const list = readRegistry(registry).filter((e) => e.key !== key);
+    studio.transaction(({ set, stateEditors }) => {
+        stateEditors.coreByProject.historic.sheetsById.forgetObject({
+            projectId: sheet.address.projectId,
+            sheetId: sheet.address.sheetId,
+            // 业务 key 跨适配层按不透明字符串传递,此处回到 core 的名义类型
+            objectKey: key,
+        });
+        set(registry.props.list, JSON.stringify(list));
+    });
+}
+/**
+ * 给 three-stdlib 版缩放手柄补一个居中的等比缩放块。drei 封装的这个
+ * 旧版手柄只有单轴/双轴和轴尖白块(XYZX/Y/Z,太小发现不了);它的拾取
+ * (axis = 拾取块 name)和拖动(axis 含 'XYZ' 即三轴同系数)逻辑原生支持
+ * 等比,所以往 gizmo/picker 的 scale 分组各加一个 name='XYZ' 的块即可,
+ * 拖动写回/撤销仍走 SelectionGizmo 现有链路。ref 回调每次渲染重挂,
+ * 这里按 name 查重保证幂等。依赖 three-stdlib 内部分组结构,升级
+ * drei/three-stdlib 时需复核。
+ */
+function ensureUniformScaleHandle(controls) {
+    // controls.gizmo 是 TransformControlsGizmo,可视/拾取分组挂在它下面
+    const gizmoScale = controls?.gizmo?.gizmo?.scale;
+    const pickerScale = controls?.gizmo?.picker?.scale;
+    if (!gizmoScale || !pickerScale)
+        return;
+    if (gizmoScale.children.some((child) => child.name === 'XYZ'))
+        return;
+    const visual = new Mesh(new BoxGeometry(0.16, 0.16, 0.16), new MeshBasicMaterial({
+        color: 0xffffff,
+        transparent: true,
+        opacity: 0.35,
+        depthTest: false,
+        depthWrite: false,
+        toneMapped: false,
+    }));
+    visual.name = 'XYZ';
+    visual.renderOrder = Infinity;
+    const hit = new Mesh(new BoxGeometry(0.26, 0.26, 0.26), new MeshBasicMaterial({ visible: false }));
+    hit.name = 'XYZ';
+    gizmoScale.add(visual);
+    pickerScale.add(hit);
+}
+/**
+ * 选中对象的操作手柄:studio 选中状态里出现登记过的对象时,
+ * 在它的节点上挂手柄(移动三轴/旋转圆环/缩放方块,由 mode 决定);
+ * 取消选中或选中别的,手柄消失。
+ * (登记见 useSelectionGizmoTarget:已放置的模型、Thingy 都在表里)
+ *
+ * 拖动写回和拖相机同一套:按下开一个 scrub,拖动中逐帧 capture
+ * (theatre 状态实时更新,属性面板/同步方都能看到),松手一次 commit
+ * ——一次拖动 = 一步撤销。轨道控制器是 makeDefault,drei 的
+ * TransformControls 拖动期间会自动禁用它,视角不会跟着转。
+ */
+export function SelectionGizmo({ hidden, mode, }) {
+    const [target, setTarget] = useState(null);
+    const invalidate = useThree((s) => s.invalidate);
+    const camera = useThree((s) => s.camera);
+    const gl = useThree((s) => s.gl);
+    const scrubRef = useRef(undefined);
+    const controlsRef = useRef(null);
+    // 中心等比块的拖动修正:three-stdlib 对 axis==='XYZ' 用
+    // |pointEnd|/|pointStart| 算系数,抓点离手柄中心越近分母越小,轻轻一拖
+    // 就是几百倍。这里在写回前改用屏幕空间径向映射:以抓手处相对手柄中心
+    // 屏幕点的方向为轴,沿轴拖 250px ≈ 2 倍,可预期、不炸。
+    const uniDragRef = useRef(null);
+    const lastPointerRef = useRef({ x: 0, y: 0 });
+    useEffect(() => {
+        const onMove = (ev) => {
+            lastPointerRef.current = { x: ev.clientX, y: ev.clientY };
+        };
+        window.addEventListener('pointermove', onMove);
+        return () => window.removeEventListener('pointermove', onMove);
+    }, []);
+    // G 键模态抓取(Blender):选中对象跟随鼠标(过起点、正对相机的平面),
+    // X/Y/Z 锁轴,左键/回车确认,右键/Esc 废弃弹回;和路径控制点共用一套
+    const { start: startGrab, active: grabActive } = useModalGrab();
+    const poseKey = usePoseSessionKey();
+    // 姿势模式期间:被摆模型的三轴手柄让位给 threeIK 操纵器(描边保留——只取
+    // 模型子树,控制点不在其中,互不干扰)
+    const isPosingTarget = !!poseKey &&
+        !!target &&
+        getPlacementEntryForObject(target.obj)?.key === poseKey;
+    useEffect(() => {
+        const studio = getStudioSync();
+        if (!studio)
+            return;
+        const sync = () => {
+            const selected = studio.selection.find((item) => getGizmoTargetEntry(item));
+            const entry = selected && getGizmoTargetEntry(selected);
+            setTarget(selected && entry
+                ? { obj: selected, node: entry.node, boxHighlight: entry.boxHighlight }
+                : null);
+            invalidate();
+        };
+        sync();
+        // 选中变化、登记表变化(路径驱动启用把相机注销了等)都重算附着目标
+        const offRegistry = onGizmoRegistryChange(sync);
+        const untapSelection = studio.onSelectionChange(sync);
+        return () => {
+            offRegistry();
+            untapSelection();
+        };
+    }, [invalidate]);
+    // G:对当前选中对象起模态抓取(写回 position;旋转/缩放的模态版暂无,
+    // R/S 只切模式)。抓取平面/写回都是世界坐标,落属性时换算回节点本地
+    useEffect(() => {
+        if (hidden || !target)
+            return;
+        const onKey = (ev) => {
+            if (ev.code !== 'KeyG')
+                return;
+            if (getPoseSession())
+                return;
+            const el = ev.target;
+            if (el &&
+                (el.tagName === 'INPUT' ||
+                    el.tagName === 'TEXTAREA' ||
+                    el.isContentEditable))
+                return;
+            // 箭头拖动中途不抢
+            if (scrubRef.current)
+                return;
+            const { obj, node } = target;
+            startGrab({
+                startPos: node.getWorldPosition(new Vector3()),
+                dragging: false,
+                capture: (scrub, worldPos) => {
+                    const local = worldPos.clone();
+                    const parent = node.parent;
+                    if (parent) {
+                        parent.updateWorldMatrix(true, false);
+                        parent.worldToLocal(local);
+                    }
+                    scrub.capture(({ set }) => set(obj.props.position, { x: local.x, y: local.y, z: local.z }));
+                },
+            });
+        };
+        window.addEventListener('keydown', onKey);
+        return () => window.removeEventListener('keydown', onKey);
+    }, [hidden, target, startGrab]);
+    // 附着节点被移出场景(对象被删/卸载)时立刻摘掉手柄:否则 React
+    // 重渲染前的空窗期里,helper 每帧更新都会撞 three 的
+    // "The attached 3D object must be a part of the scene graph" 报错
+    // (删选中的相机必现一次)。three 的 'removed' 事件和节点移除同步,
+    // 比等选中通知→setState→重渲染快一个帧
+    useEffect(() => {
+        if (!target)
+            return;
+        const node = target.node;
+        const detach = () => {
+            controlsRef.current?.detach?.();
+            setTarget((t) => (t && t.node === node ? null : t));
+        };
+        node.addEventListener('removed', detach);
+        return () => node.removeEventListener('removed', detach);
+    }, [target]);
+    // 卸载兜底:对象被撤销掉(节点已不在场景里)时不挂手柄;
+    // 模态抓取期间也不挂:两套拖动不撞车(抓取结束后自动回来);
+    // 选择模式(W)只点选不挂手柄(Blender 的 Select 工具)
+    const showControls = !hidden &&
+        !!target &&
+        !!target.node.parent &&
+        !grabActive &&
+        mode !== 'select' &&
+        !isPosingTarget;
+    // 选中轮廓:模式无关(选择模式下它是唯一的选中提示),抓取期间也跟随
+    const showOutline = !hidden && !!target && !!target.node.parent && target.boxHighlight;
+    if (!target)
+        return null;
+    return (React.createElement(React.Fragment, null,
+        showOutline && React.createElement(SelectionOutlineHighlight, { node: target.node }),
+        showControls && (React.createElement(TransformControls, { ref: (controls) => {
+                controlsRef.current = controls;
+                // 箭头本体登记为"仅编辑视角":画中画/镜头视角渲染时不入画。
+                // three 0.185 的 TransformControls 不是 Object3D,可视部分在 getHelper()
+                if (!controls)
+                    return;
+                ensureUniformScaleHandle(controls);
+                const root = typeof controls.getHelper === 'function'
+                    ? controls.getHelper()
+                    : controls;
+                return registerEditorOnly(root);
+            }, object: target.node, mode: mode, onMouseDown: () => {
+                suppressSelectBriefly();
+                scrubRef.current = getStudioSync()?.scrub();
+                invalidate();
+                const axis = controlsRef.current?.axis;
+                if (mode === 'scale' && axis === 'XYZ') {
+                    const ndc = target.node
+                        .getWorldPosition(new Vector3())
+                        .project(camera);
+                    const rect = gl.domElement.getBoundingClientRect();
+                    const cx = rect.left + ((ndc.x + 1) / 2) * rect.width;
+                    const cy = rect.top + ((1 - ndc.y) / 2) * rect.height;
+                    const p = lastPointerRef.current;
+                    let dx = p.x - cx;
+                    let dy = p.y - cy;
+                    const len = Math.hypot(dx, dy);
+                    // 抓在正中心时没有方向,兜底向屏幕下方拉=放大
+                    if (len < 4) {
+                        dx = 0;
+                        dy = 1;
+                    }
+                    else {
+                        dx /= len;
+                        dy /= len;
+                    }
+                    uniDragRef.current = {
+                        startScale: target.node.scale.clone(),
+                        startPointer: { ...p },
+                        dir: { x: dx, y: dy },
+                    };
+                }
+                else {
+                    uniDragRef.current = null;
+                }
+            }, onObjectChange: () => {
+                suppressSelectBriefly();
+                invalidate();
+                const scrub = scrubRef.current;
+                if (!scrub)
+                    return;
+                const node = target.node;
+                scrub.capture(({ set }) => {
+                    // 旋转/缩放写回的是节点本地值:theatre 的 rotation/scale 属性
+                    // 本来就是本地空间,和面板里看到的数字一致
+                    if (mode === 'rotate') {
+                        const r = node.rotation;
+                        set(target.obj.props.rotation, { x: r.x, y: r.y, z: r.z });
+                    }
+                    else if (mode === 'scale') {
+                        const uni = uniDragRef.current;
+                        if (uni && controlsRef.current?.axis === 'XYZ') {
+                            // 等比块:弃用 three-stdlib 的距离比(抓点近中心会炸),
+                            // 改屏幕空间径向映射,见 uniDragRef 注释
+                            const p = lastPointerRef.current;
+                            const along = (p.x - uni.startPointer.x) * uni.dir.x +
+                                (p.y - uni.startPointer.y) * uni.dir.y;
+                            const factor = Math.max(0.01, 1 + along / 250);
+                            node.scale.copy(uni.startScale).multiplyScalar(factor);
+                        }
+                        const s = node.scale;
+                        set(target.obj.props.scale, { x: s.x, y: s.y, z: s.z });
+                    }
+                    else {
+                        const p = node.position;
+                        set(target.obj.props.position, { x: p.x, y: p.y, z: p.z });
+                    }
+                });
+            }, onMouseUp: () => {
+                suppressSelectBriefly();
+                scrubRef.current?.commit();
+                scrubRef.current = undefined;
+                uniDragRef.current = null;
+            } }))));
+}
+/**
+ * 选中对象的轮廓描边(Blender 式,蒙版+边缘检测):没有自带选中高亮的
+ * 对象(放置的模型等)选中后由它提示选中态——模式无关,选择模式下它是
+ * 唯一的选中反馈。屏幕空间描边,不往场景挂任何网格;画中画/镜头取景/
+ * 导出不入画(镜头视角下 SelectionGizmo 整体不挂,这里随之缺席)。
+ * useFrame 优先级 1.5:在 drei Hud(优先级 1,主视角画面)之后、画中画
+ * (优先级 2)之前画,描边只叠在编辑主视角上。
+ */
+function SelectionOutlineHighlight({ node }) {
+    const invalidate = useThree((s) => s.invalidate);
+    const rendererRef = useRef(null);
+    useEffect(() => {
+        const renderer = createSelectionOutlineRenderer();
+        rendererRef.current = renderer;
+        return () => {
+            renderer.dispose();
+            rendererRef.current = null;
+        };
+    }, []);
+    // 选中切换/卸载都要触发重画:demand 模式下不 invalidate,
+    // 画面上会留着上一帧的描边残影
+    useEffect(() => {
+        invalidate();
+        return () => invalidate();
+    }, [node, invalidate]);
+    useFrame(({ gl, scene, camera, size, viewport }) => {
+        rendererRef.current?.render(gl, scene, camera, node, size, viewport.dpr);
+    }, 1.5);
+    return null;
+}