@dreamerbird/camera-studio 0.1.0 → 0.2.0

package/dist/CameraScene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CameraScene.d.ts","sourceRoot":"","sources":["../src/CameraScene.tsx"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAiB,YAAY,EAAC,MAAM,mBAAmB,CAAA;AACnE,OAAO,KASN,MAAM,OAAO,CAAA;AAsDd,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,mBAAmB,CAAA;AAiBjD,OAAO,KAAK,EAAc,UAAU,EAAC,MAAM,kBAAkB,CAAA;AAyD7D,OAAO,KAAK,EAAC,WAAW,EAAe,MAAM,aAAa,CAAA;AAG1D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,UAAU,CAAA;AA4kB9C;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,SAAS,GACrC,UAAU,GAAG,SAAS,CAMxB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,SAAS,GACrC,UAAU,CAcZ;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAC,EAAE,gBAAgB,qBAw/CxE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,EAAC,QAAQ,EAAC,EAAE;IAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAC,qBAIpE;AAuFD,8BAA8B;AAC9B,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,OAAO,GACR,EAAE;IACD,KAAK,EAAE,WAAW,CAAA;IAClB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;CACnC,QAOA"}
+{"version":3,"file":"CameraScene.d.ts","sourceRoot":"","sources":["../src/CameraScene.tsx"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAiB,YAAY,EAAC,MAAM,mBAAmB,CAAA;AACnE,OAAO,KASN,MAAM,OAAO,CAAA;AAsDd,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,mBAAmB,CAAA;AAiBjD,OAAO,KAAK,EAAc,UAAU,EAAC,MAAM,kBAAkB,CAAA;AAyD7D,OAAO,KAAK,EAAC,WAAW,EAAe,MAAM,aAAa,CAAA;AAG1D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,UAAU,CAAA;AAwmB9C;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,SAAS,GACrC,UAAU,GAAG,SAAS,CAMxB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,SAAS,GACrC,UAAU,CAcZ;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAC,EAAE,gBAAgB,qBAijDxE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,EAAC,QAAQ,EAAC,EAAE;IAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAC,qBAIpE;AAuFD,8BAA8B;AAC9B,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,OAAO,GACR,EAAE;IACD,KAAK,EAAE,WAAW,CAAA;IAClB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;CACnC,QAOA"}

package/dist/CameraScene.js

@@ -50,12 +50,25 @@ import { createHostFlows, setDropPointContext, setHostFlowsHandle, setPlacingSna
 import { importModelFile } from './assetLibrary/importModelFile';
 import { resolveControlSpec } from './poseMode/controlSpec';
 import { getUiConfig } from './uiConfig';
+import { createFirstScreenGate, getFirstScreenGate, installFirstScreenGate, resetFirstScreenGate, } from './firstScreenGate';
 import { enterPoseSession, getPoseSession, isModelDoubleClick, poseHitTest, requestPoseExit, usePoseSessionKey, } from './poseMode/poseSession';
 import { getPoseKeyframeCount, setPoseValue, writePoseKeyframe, clearPoseValue, } from './poseMode/poseTrack';
 import { savePoseFromInstance } from './poseMode/savePose';
 import { parsePoseValue, serializeLibPose } from './poseMode/poseValue';
 import { isPoseExitGuardedTarget } from './poseMode/poseExitGuard';
 import { poseStatusText } from './poseStatusText';
+/** 首屏闸门里场景内置模型(scene.glb)的登记 key */
+const SCENE_MODEL_GATE_KEY = 'scene-glb';
+/**
+ * 加载探针:Suspense 未解决时子树不挂载,mount effect 触发即
+ * 「这个资源落定了」,上报首屏闸门(firstScreenGate 机制)
+ */
+function InitialLoadProbe({ gateKey, children, }) {
+    useEffect(() => {
+        getFirstScreenGate().settle(gateKey);
+    }, [gateKey]);
+    return React.createElement(React.Fragment, null, children);
+}
 function Model({ url, selectLocked }) {
     const { nodes } = useGLTF(url);
     const thingyObjRef = useRef(undefined);
@@ -100,10 +113,11 @@ function Model({ url, selectLocked }) {
 /**
  * 导演视角初始机位/瞄准点:PerspectiveCamera/Target 的 JSX position 与
  * Agent view.reset(MainOrbitControls 登记的导演控制器)同源,改一处
- * 两处一致。
+ * 两处一致。场景单位 = 米:机位 4.5 米外、1.7 米高,瞄准胸口(0.9 米),
+ * 一个 1.8 米的人占画面约四成高,是舒服的工作取景。
  */
-const DIRECTOR_HOME_CAMERA_POSITION = [0, 0, 16];
-const DIRECTOR_HOME_TARGET_POSITION = [0, 0, 0];
+const DIRECTOR_HOME_CAMERA_POSITION = [0, 1.7, 4.5];
+const DIRECTOR_HOME_TARGET_POSITION = [0, 0.9, 0];
 /**
  * 主画面的视角控制,操作方式与 Blender 默认键位一致:
  *   中键拖动 = 旋转视角;Shift+中键 = 平移;Ctrl/Cmd+中键 = 平滑缩放;
@@ -496,6 +510,7 @@ const BACKGROUND = new Color().setRGB(0x45 / 255, 0x45 / 255, 0x45 / 255, Linear
 function GroundGrid() {
     const ref = useRef(null);
     useEffect(() => registerEditorOnly(ref.current), []);
+    // 场景单位 = 米:小格 1 米、粗线 5 米
     return (React.createElement(Grid, { ref: ref, position: [0, 0.01, 0], args: [100, 100], cellSize: 1, cellColor: "#9b9ba1", sectionSize: 5, sectionColor: "#aeaeb6", fadeDistance: 80, fadeStrength: 1, infiniteGrid: true, raycast: () => null }));
 }
 /**
@@ -1419,6 +1434,30 @@ export function CameraScene({ project, onFlows, onError }) {
     const handleTogglePath = useMemo(() => () => toggleFrame('path'), [toggleFrame]);
     // 稳定引用:行为不变(setPipVisible 取反),与 handleToggleModel/Path 同模式
     const handleTogglePip = useCallback(() => setPipVisible((v) => !v), []);
+    // 首屏闸门(firstScreenGate 机制):创建即安装——子树 effect 先于父 effect
+    // 运行,useState 初始化器(渲染期)是子树 effect 能拿到闸门的最早时机;
+    // 卸载时若单值仍是本闸门则复位(重挂载由新实例重装)
+    const [firstScreenReady, setFirstScreenReady] = useState(false);
+    const [coverGone, setCoverGone] = useState(false);
+    const [firstScreenGate] = useState(() => {
+        const gate = createFirstScreenGate(() => setFirstScreenReady(true));
+        gate.expect(SCENE_MODEL_GATE_KEY);
+        installFirstScreenGate(gate);
+        return gate;
+    });
+    useEffect(() => {
+        return () => {
+            if (getFirstScreenGate() === firstScreenGate)
+                resetFirstScreenGate();
+        };
+    }, [firstScreenGate]);
+    // 遮罩淡出(0.3s)+ 余量后卸载,不依赖 transitionend 单一路径
+    useEffect(() => {
+        if (!firstScreenReady)
+            return;
+        const t = setTimeout(() => setCoverGone(true), 600);
+        return () => clearTimeout(t);
+    }, [firstScreenReady]);
     return (React.createElement(SceneI18nRoot, null,
         React.createElement("div", { style: {
                 height: '100vh',
@@ -1595,7 +1634,8 @@ export function CameraScene({ project, onFlows, onError }) {
                         React.createElement("boxGeometry", { attach: "geometry" }),
                         React.createElement("meshPhongMaterial", { attach: "material", color: "red" })),
                     React.createElement(Suspense, { fallback: null },
-                        React.createElement(Model, { url: sceneGLB, selectLocked: !!placing })),
+                        React.createElement(InitialLoadProbe, { gateKey: SCENE_MODEL_GATE_KEY },
+                            React.createElement(Model, { url: sceneGLB, selectLocked: !!placing }))),
                     placing && (React.createElement(Suspense, { fallback: null },
                         React.createElement(PlacementRigErrorBoundary, { onCancel: () => {
                                 cancelPlacing();
@@ -1614,7 +1654,28 @@ export function CameraScene({ project, onFlows, onError }) {
                             placePresetPath(presetDrag, p);
                             setPresetDrag(null);
                         }, onCancel: () => setPresetDrag(null) })),
-                    React.createElement(GroundGrid, null))))));
+                    React.createElement(GroundGrid, null))),
+            !coverGone && (React.createElement("div", { "aria-hidden": true, style: {
+                    position: 'absolute',
+                    inset: 0,
+                    zIndex: getUiConfig().zIndexBase + 100,
+                    background: '#454545',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    opacity: firstScreenReady ? 0 : 1,
+                    transition: 'opacity 0.3s ease',
+                    pointerEvents: firstScreenReady ? 'none' : 'auto',
+                } },
+                React.createElement("style", null, `@keyframes cameraStudioFirstScreenSpin{to{transform:rotate(360deg)}}`),
+                React.createElement("div", { style: {
+                        width: 28,
+                        height: 28,
+                        borderRadius: '50%',
+                        border: '3px solid rgba(255,255,255,0.25)',
+                        borderTopColor: '#ffffff',
+                        animation: 'cameraStudioFirstScreenSpin 0.8s linear infinite',
+                    } }))))));
 }
 /**
  * i18n 嵌套判定(spec §7):宿主树已包 studio 的 I18nProvider →

package/dist/PlacementManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlacementManager.d.ts","sourceRoot":"","sources":["../src/PlacementManager.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"PlacementManager.d.ts","sourceRoot":"","sources":["../src/PlacementManager.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,QAAQ,EAAU,MAAM,EAAE,YAAY,EAAC,MAAM,mBAAmB,CAAA;AAW7E,OAAO,KAQN,MAAM,OAAO,CAAA;AAUd,OAAO,KAAK,EAAC,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAkB,MAAM,OAAO,CAAA;AAQ1E,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,wBAAwB,CAAA;AAoCnD,OAAO,KAAK,EAAC,UAAU,EAAY,MAAM,sBAAsB,CAAA;AAgB/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gCAAgC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAAA;CAC5C,CAAA;AAED,4CAA4C;AAC5C,KAAK,qBAAqB,GAAG,cAAc,GAAG;IAAC,OAAO,EAAE,IAAI,CAAA;CAAC,CAAA;AAE7D,KAAK,eAAe,GAChB;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAC5C;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAA;AAEtC,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,eAAe,CAAA;CACxB,CAAA;AAED,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,eAAe,CAAA;AA8DnD,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,GACrB,cAAc,GAAG,SAAS,CAE5B;AAED,2DAA2D;AAC3D,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,GACrB;IAAC,KAAK,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAA;CAAC,GAAG,SAAS,CAEtD;AAED,yCAAyC;AACzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ9D;AAgCD,iCAAiC;AACjC,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,QASxE;AAED,qCAAqC;AACrC,wBAAgB,oBAAoB,IAAI,WAAW,CAAC,QAAQ,CAAC,CAE5D;AAqBD,mBAAmB;AACnB,wBAAgB,mBAAmB,IAAI,WAAW,CAAC,QAAQ,CAAC,CAE3D;AAKD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,GAAG,IAAI,CAGzE;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAG1D;AAaD,wBAAgB,kBAAkB,IAAI,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAE/D;AAED;;;;;;GAMG;AACH,KAAK,yBAAyB,GAAG;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAC,CAAA;AAaxE,qBAAqB;AACrB,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAKtE;AAMD,gDAAgD;AAChD,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,GACrB,yBAAyB,GAAG,SAAS,CAEvC;AAED,+CAA+C;AAC/C,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,EACtB,IAAI,EAAE,QAAQ,EACd,IAAI,CAAC,EAAE;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAC,GAC9B,MAAM,IAAI,CAUZ;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,EACtD,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,EACzC,OAAO,UAAO,EACd,IAAI,CAAC,EAAE;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAC,QAUhC;AAQD,2CAA2C;AAC3C,wBAAgB,kBAAkB,YAEjC;AAED,0CAA0C;AAC1C,wBAAgB,qBAAqB,SAEpC;AAED;gDACgD;AAChD,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,GACrC,cAAc,EAAE,CAOlB;AAED,uCAAuC;AACvC,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC,CAE1C;AAED;2DAC2D;AAC3D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAczE;AA0ED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM;;;yBAMtD,IAAI;qCA4BuC,UAAU;;4BAqB1D;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC;iCAiCjC,UAAU,SAAS;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC;;;;;EA2B/D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,OAAO,EAAE,YAAY,CAAA;IACrB,SAAS,EAAE,CAAC,KAAK,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,IAAI,CAAA;IAC7D,QAAQ,EAAE,MAAM,IAAI,CAAA;IACpB,gCAAgC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B,qBAMA;AAyND,4CAA4C;AAC5C,qBAAa,yBAA0B,SAAQ,KAAK,CAAC,SAAS,CAC5D;IAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAC,EACjD;IAAC,MAAM,EAAE,OAAO,CAAA;CAAC,CAClB;IACC,KAAK;;MAAkB;IACvB,MAAM,CAAC,wBAAwB;;;IAG/B,iBAAiB,CAAC,GAAG,EAAE,OAAO;IAI9B,MAAM;CAGP;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,OAAO,EACP,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,GACb,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,QAAQ,CAAA;IACjB,YAAY,EAAE,qBAAqB,GAAG,IAAI,CAAA;IAC1C,WAAW,EAAE,MAAM,IAAI,CAAA;IACvB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC3D,4BAqCA;AA6ED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,OAAsB,GAC1B,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,aAAa,EAAE,CAAA;CAAC,CAAC,CAiBtD;AA8kBD,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEnE;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC,CA+BrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,QAczD;AAuCD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EACN,IAAI,GACL,EAAE;IACD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,SAAS,CAAA;CAChB,4BAkOA"}

package/dist/PlacementManager.js

@@ -14,6 +14,8 @@ import { SkeletonUtils } from 'three-stdlib';
 import { registerBoneAnchors, unregisterBoneAnchors } from './boneAnchors';
 import { notifyTargetRegistryChange, sheetObjectExists } from './aimTargets';
 import { createGLTFLoader } from './assetLibrary/gltfLoader';
+import { metricScaleFactor } from './assetLibrary/exportGLB';
+import { getFirstScreenGate } from './firstScreenGate';
 import { getLibrary } from './assetLibrary/library';
 import { LibraryError } from './assetLibrary/source';
 import { entryOptions } from './assetLibrary/options';
@@ -327,14 +329,18 @@ function usePlacementsList(sheet) {
     }, [registry]);
     return list;
 }
-/** 归一化:任意 FBX 单位差异很大,统一缩放到最大边 5 个世界单位,底部对齐落点 */
+/** 米制兜底:入库时源单位已换算成米烘进资产(exportGLB.bakeMetricScale),
+ * 这里只对未烘焙来源(local 直接拖文件、旧库存)纠偏——已烘焙资产算出
+ * 的系数恰好是 1,theatre 缩放属性得以 1 为干净基线。底部对齐落点。
+ * ⚠️ 旧库存是「归一化成 5 单位」时代的资产(2026-10-21 前),量出来
+ * maxDim=5 不会触发厘米换算,放出来是 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,
+            scale: maxDim > 0 ? metricScaleFactor(maxDim) : 1,
             // lift 是模型局部单位,放进 scale 过的组里后底部正好落在 y=0
             lift: -box.min.y,
         };
@@ -664,6 +670,19 @@ export function PlacedModels({ sheet, project, pendingEntry, onPersisted, select
     const entries = pendingEntry && !list.some((e) => e.key === pendingEntry.key)
         ? [...list, pendingEntry]
         : list;
+    // 首屏闸门(firstScreenGate 机制):先登记本批要等的模型、再报工程就绪,
+    // 顺序不可换——先报就绪而 pending 为空会提前揭幕。已落定的 key gate
+    // 内部防回加,清单变化重跑只补登新条目;落定后全部调用是 no-op
+    const entriesKey = entries.map((e) => e.key).join('|');
+    useEffect(() => {
+        if (!ready)
+            return;
+        const gate = getFirstScreenGate();
+        for (const e of entries)
+            gate.expect(e.key);
+        gate.setProjectReady();
+        // entries 用 join 串做依赖:内容没变不重复跑
+    }, [ready, entriesKey]);
     if (!ready)
         return null;
     return (React.createElement(React.Fragment, null, entries.map((entry) => (React.createElement(Suspense, { key: entry.key, fallback: null },
@@ -745,6 +764,12 @@ function LibraryPlacedModel({ entry, project, sheet, onPersisted, selectLocked,
 }
 /** 已加载 Group 之后的公共逻辑:克隆、归一化、动画 mixer、点选菜单、持久化 */
 function PlacedModelCore({ entry, sheet, group, animations, sourceType, onPersisted, selectLocked, onObjectMenu, }) {
+    // 两条加载路径(库 GLB / 本地 FBX)都在这里汇合:挂载即「这个模型
+    // 落定了」,上报首屏闸门(失败路径由 PlacedModelErrorBoundary 上报)
+    useEffect(() => {
+        getFirstScreenGate().settle(entry.key);
+        // entry.key 挂载期内不变
+    }, []);
     const additionalProps = useMemo(() => {
         const modelEntryId = sourceType === 'library' ? entry.libraryEntryId : undefined;
         const props = {
@@ -1176,6 +1201,8 @@ class PlacedModelErrorBoundary extends React.Component {
     }
     componentDidCatch(err) {
         console.warn(`[placement] 模型 ${this.props.entry.key} 加载失败`, err);
+        // 失败也是落定:首屏闸门不能因一个坏模型一直挂遮罩
+        getFirstScreenGate().settle(this.props.entry.key);
         // Agent models.create 正等着挂载完成(Task 8):失败必须 reject waiter,
         // 不能悬挂;UI 路径没有 waiter,rejectPlacement 是 no-op
         rejectPlacement(this.props.entry.key, err);

package/dist/assetLibrary/exportGLB.d.ts

@@ -1,5 +1,30 @@
 import { Group } from 'three';
 import type { AnimationClip, Object3D } from 'three';
+/**
+ * 场景单位 = 米(2026-10-21 起,替代此前「最长边统一拉成 5 单位」的
+ * 归一化约定)。glTF 标准本来就是米,人高 1.8 单位、网格 1 小格 = 1 米,
+ * 模型之间保持真实世界的相对大小(车 4.5 / 人 1.8 / 杯子 0.1)。
+ * PlacementManager 的 useNormalizedModel 用同一套换算兜底未烘焙来源。
+ */
+export declare const SCENE_UNIT_METERS = 1;
+/**
+ * 厘米源判定阈值:最长边超过这个数就按厘米源处理(÷100)。
+ * Mixamo 等 FBX 是厘米(人 180),标准 GLB 是米(人 1.8)。取 50 是因为
+ * 米制模型最长边到 50(=50 米,一栋楼)在本系统里罕见,而厘米源几乎
+ * 都远超(一个人就 180)。猜错的入口(超大道具/建筑)保留手动改缩放。
+ */
+export declare const CENTIMETER_SOURCE_THRESHOLD = 50;
+/** 源尺寸最长边 → 米制换算系数(米源返回 1,厘米源返回 0.01) */
+export declare function metricScaleFactor(maxDim: number): number;
+/**
+ * 把「源单位 → 米」的换算系数烘进根节点 scale(入库前置)。
+ * 源文件单位五花八门(Mixamo FBX 是厘米、GLB 多是米),烘过之后任何
+ * 模型都是真实米制尺寸,放置时 theatre 对象的缩放属性才能以 1 为
+ * 干净基线(1 = 真实大小,2 = 两倍大)。只动根节点变换:蒙皮随骨骼
+ * 世界变换正确缩放,骨骼局部数据(动画轨道寻址的那层)不受影响。
+ * 返回应用的系数(1 = 本来就是米,没动)。
+ */
+export declare function bakeMetricScale(root: Object3D): number;
 /**
  * 移除无法导出的贴图(image 数据缺失)。
  * FBX 常引用本机不存在的外部贴图文件,加载失败后留下 image 为空的 Texture,

package/dist/assetLibrary/exportGLB.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exportGLB.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/exportGLB.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,EAAC,MAAM,OAAO,CAAA;AACjC,OAAO,KAAK,EAAC,aAAa,EAAQ,QAAQ,EAAU,MAAM,OAAO,CAAA;AAIjE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CA6B3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAoBnD;AAgBD,0CAA0C;AAC1C,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,CAQnE;AAED,6BAA6B;AAC7B,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAEtB"}
+{"version":3,"file":"exportGLB.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/exportGLB.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,EAAU,MAAM,OAAO,CAAA;AAChD,OAAO,KAAK,EAAC,aAAa,EAAQ,QAAQ,EAAU,MAAM,OAAO,CAAA;AAIjE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAElC;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAA;AAE7C,yCAAyC;AACzC,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAStD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CA6B3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAoBnD;AAgBD,0CAA0C;AAC1C,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,CAgBnE;AAED,6BAA6B;AAC7B,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAEtB"}

package/dist/assetLibrary/exportGLB.js

@@ -1,6 +1,44 @@
-import { Bone, Group } from 'three';
+import { Bone, Box3, Group, Vector3 } from 'three';
 import { GLTFExporter } from 'three-stdlib';
 import { compressGLBDraco } from './draco';
+/**
+ * 场景单位 = 米(2026-10-21 起,替代此前「最长边统一拉成 5 单位」的
+ * 归一化约定)。glTF 标准本来就是米,人高 1.8 单位、网格 1 小格 = 1 米,
+ * 模型之间保持真实世界的相对大小(车 4.5 / 人 1.8 / 杯子 0.1)。
+ * PlacementManager 的 useNormalizedModel 用同一套换算兜底未烘焙来源。
+ */
+export const SCENE_UNIT_METERS = 1;
+/**
+ * 厘米源判定阈值:最长边超过这个数就按厘米源处理(÷100)。
+ * Mixamo 等 FBX 是厘米(人 180),标准 GLB 是米(人 1.8)。取 50 是因为
+ * 米制模型最长边到 50(=50 米,一栋楼)在本系统里罕见,而厘米源几乎
+ * 都远超(一个人就 180)。猜错的入口(超大道具/建筑)保留手动改缩放。
+ */
+export const CENTIMETER_SOURCE_THRESHOLD = 50;
+/** 源尺寸最长边 → 米制换算系数(米源返回 1,厘米源返回 0.01) */
+export function metricScaleFactor(maxDim) {
+    return maxDim > CENTIMETER_SOURCE_THRESHOLD ? 0.01 : SCENE_UNIT_METERS;
+}
+/**
+ * 把「源单位 → 米」的换算系数烘进根节点 scale(入库前置)。
+ * 源文件单位五花八门(Mixamo FBX 是厘米、GLB 多是米),烘过之后任何
+ * 模型都是真实米制尺寸,放置时 theatre 对象的缩放属性才能以 1 为
+ * 干净基线(1 = 真实大小,2 = 两倍大)。只动根节点变换:蒙皮随骨骼
+ * 世界变换正确缩放,骨骼局部数据(动画轨道寻址的那层)不受影响。
+ * 返回应用的系数(1 = 本来就是米,没动)。
+ */
+export function bakeMetricScale(root) {
+    const box = new Box3().setFromObject(root);
+    const size = box.getSize(new Vector3());
+    const maxDim = Math.max(size.x, size.y, size.z);
+    if (!(maxDim > 0))
+        return 1;
+    const factor = metricScaleFactor(maxDim);
+    if (factor === 1)
+        return 1;
+    root.scale.multiplyScalar(factor);
+    return factor;
+}
 /**
  * 移除无法导出的贴图(image 数据缺失)。
  * FBX 常引用本机不存在的外部贴图文件,加载失败后留下 image 为空的 Texture,
@@ -75,6 +113,10 @@ export function exportModelGLB(root) {
     if (stripped > 0) {
         console.warn(`[assetLibrary] ${stripped} 张贴图数据无效(源文件引用的贴图缺失或加载失败),已移除后继续导出,模型将以灰模/部分贴图入库`);
     }
+    const factor = bakeMetricScale(root);
+    if (factor !== 1) {
+        console.info(`[assetLibrary] 已把源尺寸换算成米烘进模型(系数 ${factor.toFixed(4)}),放置时缩放基线为 1 = 真实大小`);
+    }
     return exportGLB(root, []).then(compressGLBDraco);
 }
 /** 动作入库:骨骼树克隆 + 单条动画,不含网格 */

package/dist/assetLibrary/exportGLB.test.js

@@ -1,5 +1,5 @@
-import { Bone, BoxGeometry, Group, Mesh, MeshBasicMaterial, MeshStandardMaterial, Texture, } from 'three';
-import { cloneBoneTree, exportModelGLB, stripInvalidTextures } from './exportGLB';
+import { Bone, Box3, BoxGeometry, Group, Mesh, MeshBasicMaterial, MeshStandardMaterial, Texture, Vector3, } from 'three';
+import { CENTIMETER_SOURCE_THRESHOLD, bakeMetricScale, cloneBoneTree, exportModelGLB, metricScaleFactor, stripInvalidTextures, } from './exportGLB';
 describe('cloneBoneTree', () => {
     it('只保留骨骼节点(名字/变换),剔除网格', () => {
         const root = new Group();
@@ -70,4 +70,58 @@ describe('exportModelGLB', () => {
         expect(glb.byteLength).toBeGreaterThan(0);
         expect(mat.map).toBeNull();
     });
+    it('入库时把厘米源换算成米烘进根节点缩放(放置时缩放基线才是 1)', async () => {
+        // 模拟 Mixamo FBX 厘米单位:180 单位高的人
+        const root = new Group();
+        root.add(new Mesh(new BoxGeometry(50, 180, 30), new MeshBasicMaterial()));
+        const glb = await exportModelGLB(root);
+        expect(glb.byteLength).toBeGreaterThan(0);
+        expect(root.scale.x).toBeCloseTo(0.01, 6);
+        expect(root.scale.y).toBe(root.scale.x);
+        expect(root.scale.z).toBe(root.scale.x);
+    });
+});
+describe('metricScaleFactor', () => {
+    it('厘米源(超过阈值)换算 0.01,米源不动', () => {
+        expect(metricScaleFactor(180)).toBe(0.01);
+        expect(metricScaleFactor(1.8)).toBe(1);
+    });
+    it('阈值边界:恰好阈值按米,超过才按厘米', () => {
+        expect(metricScaleFactor(CENTIMETER_SOURCE_THRESHOLD)).toBe(1);
+        expect(metricScaleFactor(CENTIMETER_SOURCE_THRESHOLD + 0.01)).toBe(0.01);
+    });
+});
+describe('bakeMetricScale', () => {
+    it('厘米源烘成米制真实尺寸(180 高的人 → 1.8)', () => {
+        const root = new Group();
+        root.add(new Mesh(new BoxGeometry(50, 180, 30), new MeshBasicMaterial()));
+        expect(bakeMetricScale(root)).toBeCloseTo(0.01, 6);
+        expect(root.scale.x).toBeCloseTo(0.01, 6);
+        // 烘完最长边 = 1.8 场景单位(米),人高占比不变
+        const box = new Box3().setFromObject(root);
+        expect(box.getSize(new Vector3()).y).toBeCloseTo(1.8, 6);
+    });
+    it('米制模型不动(幂等,重烘已烘焙资产系数为 1)', () => {
+        const root = new Group();
+        root.add(new Mesh(new BoxGeometry(1.8, 1.8, 1.8), new MeshBasicMaterial()));
+        expect(bakeMetricScale(root)).toBe(1);
+        expect(root.scale.x).toBe(1);
+    });
+    it('空模型(无边几何时)返回 1 且不动缩放', () => {
+        const root = new Group();
+        expect(bakeMetricScale(root)).toBe(1);
+        expect(root.scale.x).toBe(1);
+    });
+    it('骨骼局部数据不受影响(动画轨道寻址的那层)', () => {
+        const root = new Group();
+        const hips = new Bone();
+        hips.name = 'Hips';
+        hips.position.set(0, 90, 0);
+        const mesh = new Mesh(new BoxGeometry(50, 180, 30), new MeshBasicMaterial());
+        hips.add(mesh);
+        root.add(hips);
+        bakeMetricScale(root);
+        expect(hips.position.y).toBe(90); // 只有根节点 scale 变了
+        expect(root.scale.x).toBeCloseTo(0.01, 6);
+    });
 });

package/dist/assetLibrary/seedAssetsManifest.js

@@ -3,7 +3,7 @@ export const seedAssetsManifest = {
         {
             key: 'y-bot',
             file: 'Y Bot.glb',
-            contentHash: '95cbcdd2192dbe68',
+            contentHash: 'fc55d96ed9b27445',
             name: 'Y Bot',
             rig: 'rig-16a71e249f45355b',
             boneCount: 117,

package/dist/firstScreenGate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 首屏就绪闸门(2026-10-22):聚合「工程就绪 + 首批场景资源加载落定」,
+ * 就绪前 CameraScene 盖加载遮罩——此前顶栏/轴向控制器等同步部件首帧就画,
+ * 模型和面板走各自异步(Suspense fallback=null / 库加载)settled 才补,
+ * 开场观感参差。闸门只闸首屏:落定一次后,后续放置/加载不再触发遮盖。
+ *
+ * 模块级单值通路(与 getLibrary/poseSession 同风格):CameraScene 创建并
+ * 安装;PlacementManager 各层经 getFirstScreenGate() 上报,免层层传 prop;
+ * 未安装时返回 no-op(测试或宿主绕过 CameraScene 直用 PlacementManager 不炸)。
+ */
+export interface FirstScreenGate {
+    /** 工程就绪(useProjectReady 变真时调;幂等) */
+    setProjectReady(): void;
+    /** 登记一个首屏要等的资源;已落定过的 key 不重复登记(清单重扫防回加) */
+    expect(key: string): void;
+    /** 上报一个资源落定(加载成功或失败都算;未登记的 key 忽略) */
+    settle(key: string): void;
+    /** 落定后 expect/settle 全是 no-op */
+    readonly fired: boolean;
+}
+export declare const FIRST_SCREEN_TIMEOUT_MS = 15000;
+export declare function createFirstScreenGate(onReady: () => void, timeoutMs?: number, warn?: (msg: string) => void): FirstScreenGate;
+/** CameraScene 装配期调用(必须在子树 effect 之前,见调用点注释) */
+export declare function installFirstScreenGate(gate: FirstScreenGate): void;
+export declare function getFirstScreenGate(): FirstScreenGate;
+/** CameraScene 卸载/测试复位用 */
+export declare function resetFirstScreenGate(): void;
+//# sourceMappingURL=firstScreenGate.d.ts.map

package/dist/firstScreenGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firstScreenGate.d.ts","sourceRoot":"","sources":["../src/firstScreenGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,eAAe,IAAI,IAAI,CAAA;IACvB,2CAA2C;IAC3C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,sCAAsC;IACtC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED,eAAO,MAAM,uBAAuB,QAAQ,CAAA;AAE5C,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,IAAI,EACnB,SAAS,GAAE,MAAgC,EAC3C,IAAI,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAmB,GACzC,eAAe,CA8CjB;AAYD,gDAAgD;AAChD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAElE;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AAED,2BAA2B;AAC3B,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/firstScreenGate.js

@@ -0,0 +1,67 @@
+export const FIRST_SCREEN_TIMEOUT_MS = 15000;
+export function createFirstScreenGate(onReady, timeoutMs = FIRST_SCREEN_TIMEOUT_MS, warn = console.warn) {
+    const pending = new Set();
+    const settled = new Set();
+    let projectReady = false;
+    let fired = false;
+    // 兜底:某个资源悬挂(网络卡死等)不能让用户永远看遮罩,超时强制揭幕
+    const timer = setTimeout(() => {
+        warn(`[firstScreen] 首屏等待超过 ${timeoutMs}ms 强制揭幕(未落定:${[...pending].join(', ') || '无'};工程就绪:${projectReady})`);
+        fire();
+    }, timeoutMs);
+    // Node 的 Timeout 才有 unref(浏览器返回 number):防测试进程被计时器挂住
+    if (typeof timer === 'object' && typeof timer.unref === 'function') {
+        timer.unref();
+    }
+    function fire() {
+        if (fired)
+            return;
+        fired = true;
+        clearTimeout(timer);
+        onReady();
+    }
+    function check() {
+        if (projectReady && pending.size === 0)
+            fire();
+    }
+    return {
+        get fired() {
+            return fired;
+        },
+        setProjectReady() {
+            projectReady = true;
+            check();
+        },
+        expect(key) {
+            if (fired || settled.has(key))
+                return;
+            pending.add(key);
+        },
+        settle(key) {
+            if (fired || !pending.has(key))
+                return;
+            pending.delete(key);
+            settled.add(key);
+            check();
+        },
+    };
+}
+/** 未安装时的默认闸门:fired=true 的 no-op,上报全部吞掉 */
+const noopGate = {
+    fired: true,
+    setProjectReady() { },
+    expect() { },
+    settle() { },
+};
+let current = noopGate;
+/** CameraScene 装配期调用(必须在子树 effect 之前,见调用点注释) */
+export function installFirstScreenGate(gate) {
+    current = gate;
+}
+export function getFirstScreenGate() {
+    return current;
+}
+/** CameraScene 卸载/测试复位用 */
+export function resetFirstScreenGate() {
+    current = noopGate;
+}

package/dist/firstScreenGate.test.d.ts

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

package/dist/firstScreenGate.test.d.ts.map

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

package/dist/firstScreenGate.test.js

@@ -0,0 +1,83 @@
+import { createFirstScreenGate } from './firstScreenGate';
+describe('createFirstScreenGate', () => {
+    it('工程就绪且无可等资源 → 立即落定', () => {
+        const onReady = jest.fn();
+        const gate = createFirstScreenGate(onReady);
+        expect(onReady).not.toHaveBeenCalled();
+        gate.setProjectReady();
+        expect(onReady).toHaveBeenCalledTimes(1);
+        expect(gate.fired).toBe(true);
+    });
+    it('有待载资源:全部 settle 且工程就绪才落定(先载完后就绪也成立)', () => {
+        const onReady = jest.fn();
+        const gate = createFirstScreenGate(onReady);
+        gate.expect('a');
+        gate.expect('b');
+        gate.settle('a');
+        gate.settle('b');
+        expect(onReady).not.toHaveBeenCalled(); // 工程未就绪
+        gate.setProjectReady();
+        expect(onReady).toHaveBeenCalledTimes(1);
+    });
+    it('部分 settle 不落定', () => {
+        const onReady = jest.fn();
+        const gate = createFirstScreenGate(onReady);
+        gate.expect('a');
+        gate.expect('b');
+        gate.setProjectReady();
+        gate.settle('a');
+        expect(onReady).not.toHaveBeenCalled();
+        gate.settle('b');
+        expect(onReady).toHaveBeenCalledTimes(1);
+    });
+    it('未登记的 settle 被忽略,不影响计数', () => {
+        const onReady = jest.fn();
+        const gate = createFirstScreenGate(onReady);
+        gate.expect('a');
+        gate.settle('陌生人');
+        gate.setProjectReady();
+        expect(onReady).not.toHaveBeenCalled();
+        gate.settle('a');
+        expect(onReady).toHaveBeenCalledTimes(1);
+    });
+    it('已落定的 key 再 expect 不回加(放置清单重扫场景)', () => {
+        const onReady = jest.fn();
+        const gate = createFirstScreenGate(onReady);
+        gate.expect('a');
+        gate.setProjectReady();
+        gate.settle('a');
+        expect(onReady).toHaveBeenCalledTimes(1);
+        // 清单重扫又把 a 登记一遍 + 新条目 b —— 闸门已落定,全部忽略
+        gate.expect('a');
+        gate.expect('b');
+        expect(onReady).toHaveBeenCalledTimes(1);
+    });
+    it('落定只触发一次(setProjectReady/settle 重复调用幂等)', () => {
+        const onReady = jest.fn();
+        const gate = createFirstScreenGate(onReady);
+        gate.setProjectReady();
+        gate.setProjectReady();
+        gate.settle('从未登记');
+        expect(onReady).toHaveBeenCalledTimes(1);
+    });
+    it('超时强制揭幕并告警,之后不再重复触发', () => {
+        jest.useFakeTimers();
+        try {
+            const onReady = jest.fn();
+            const warn = jest.fn();
+            const gate = createFirstScreenGate(onReady, 5000, warn);
+            gate.expect('卡住的模型');
+            jest.advanceTimersByTime(5000);
+            expect(warn).toHaveBeenCalledTimes(1);
+            expect(warn.mock.calls[0][0]).toContain('卡住的模型');
+            expect(onReady).toHaveBeenCalledTimes(1);
+            // 超时后迟到的 settle 不再触发
+            gate.settle('卡住的模型');
+            jest.advanceTimersByTime(10000);
+            expect(onReady).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            jest.useRealTimers();
+        }
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamerbird/camera-studio",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,11 +18,6 @@
     "dist/**/*",
     "assets/**/*"
   ],
-  "scripts": {
-    "build:ts": "tsc -b tsconfig.json",
-    "build:api": "tsc -b tsconfig.json && api-extractor run --local --config devEnv/api-extractor.json",
-    "clean": "rimraf dist tsconfig.tsbuildinfo"
-  },
   "peerDependencies": {
     "@dreamerbird/core": "*",
     "@dreamerbird/studio": "*",
@@ -32,9 +27,6 @@
     "three": ">=0.185"
   },
   "dependencies": {
-    "@dreamerbird/dataverse": "1.0.0",
-    "@dreamerbird/r3f": "1.0.0",
-    "@dreamerbird/react": "1.0.0",
     "@dreamerbird/threeik": "0.2.1",
     "@gltf-transform/core": "^4.0.0",
     "@gltf-transform/extensions": "^4.0.0",
@@ -43,7 +35,10 @@
     "@react-three/drei": "^10.7.8",
     "draco3dgltf": "^1.5.7",
     "styled-components": "^6.5.3",
-    "three-stdlib": "^2.36.1"
+    "three-stdlib": "^2.36.1",
+    "@dreamerbird/dataverse": "1.0.0",
+    "@dreamerbird/r3f": "1.0.0",
+    "@dreamerbird/react": "1.0.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.28.6",
@@ -58,5 +53,10 @@
     "react-dom": "^19.2.0",
     "three": "^0.185.1",
     "typescript": "5.6.3"
+  },
+  "scripts": {
+    "build:ts": "tsc -b tsconfig.json",
+    "build:api": "tsc -b tsconfig.json && api-extractor run --local --config devEnv/api-extractor.json",
+    "clean": "rimraf dist tsconfig.tsbuildinfo"
   }
 }