@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/dropPoint.test.js

@@ -0,0 +1,174 @@
+import { Group, Mesh, MeshBasicMaterial, PerspectiveCamera, PlaneGeometry, Raycaster, Vector3, } from 'three';
+import { computeDropPoint, computeViewPlanePoint, computeVerticalConstraintPoint, computeHorizontalConstraintPoint, } from './dropPoint';
+const rect = { left: 0, top: 0, width: 800, height: 600 };
+function groundCam() {
+    const c = new PerspectiveCamera(50, 800 / 600, 0.1, 1000);
+    c.position.set(0, 10, 20);
+    c.lookAt(0, 0, 0);
+    c.updateMatrixWorld();
+    return c;
+}
+describe('computeDropPoint', () => {
+    it('指向地面:命中 y=0 平面', () => {
+        const p = computeDropPoint(new Raycaster(), groundCam(), new Set(), rect, 400, 300);
+        expect(p.y).toBeCloseTo(0, 6);
+        expect(p.x).toBeCloseTo(0, 6);
+        expect(p.z).toBeCloseTo(0, 6);
+    });
+    it('视线朝天:退到前方 30 个单位并压到地面', () => {
+        const c = new PerspectiveCamera(50, 800 / 600, 0.1, 1000);
+        c.position.set(0, 10, 20);
+        c.lookAt(0, 30, -10); // 抬头,中心射线打不到地面
+        c.updateMatrixWorld();
+        const p = computeDropPoint(new Raycaster(), c, new Set(), rect, 400, 300);
+        expect(p.y).toBe(0);
+        expect(p.z).toBeCloseTo(-4.96, 1);
+    });
+    it('登记过的表面优先于地面', () => {
+        const slab = new Mesh(new PlaneGeometry(100, 100), new MeshBasicMaterial());
+        slab.rotation.x = -Math.PI / 2;
+        slab.position.y = 2;
+        slab.updateMatrixWorld();
+        const p = computeDropPoint(new Raycaster(), groundCam(), new Set([slab]), rect, 400, 300);
+        expect(p.y).toBeCloseTo(2, 6);
+    });
+    it('未登记的物体不参与命中(地面兜底)', () => {
+        const p = computeDropPoint(new Raycaster(), groundCam(), new Set(), rect, 400, 300);
+        expect(p.y).toBeCloseTo(0, 6);
+    });
+    it('相机贴地:脚下 0.5 以内的地面命中被丢弃,回退前方 30 压到地面', () => {
+        // 相机 y=0.3 斜向下看:地面命中距相机 ≈0.424(<0.5),没有放置意义
+        const c = new PerspectiveCamera(50, 800 / 600, 0.1, 1000);
+        c.position.set(0, 0.3, 0);
+        c.lookAt(0, 0, -0.3);
+        c.updateMatrixWorld();
+        const p = computeDropPoint(new Raycaster(), c, new Set(), rect, 400, 300);
+        // 不是脚下那个命中(那在 z≈-0.3),而是前方 30 个单位压到地面
+        expect(p.y).toBe(0);
+        expect(p.x).toBeCloseTo(0, 6);
+        expect(p.z).toBeCloseTo(-21.21, 1);
+    });
+    it('命中表面比地面还远时选地面', () => {
+        // 竖直平面在 z=-10:中心射线先命中地面(原点,t≈22.4),
+        // 平面命中在 (0,-5,-10),t≈33.5,更远 → 选地面
+        const wall = new Mesh(new PlaneGeometry(100, 100), new MeshBasicMaterial());
+        wall.position.set(0, 0, -10);
+        wall.updateMatrixWorld();
+        const p = computeDropPoint(new Raycaster(), groundCam(), new Set([wall]), rect, 400, 300);
+        expect(p.y).toBeCloseTo(0, 6);
+        expect(p.x).toBeCloseTo(0, 6);
+        expect(p.z).toBeCloseTo(0, 6);
+    });
+    it('命中登记根内部的网格:out.surfaceRoot 回填到登记根(不是深层网格)', () => {
+        // 登记根是个分组,里面套一层子分组再放网格(模拟放置模型的实例结构)
+        const root = new Group();
+        const inner = new Group();
+        const slab = new Mesh(new PlaneGeometry(100, 100), new MeshBasicMaterial());
+        slab.rotation.x = -Math.PI / 2;
+        slab.position.y = 2;
+        inner.add(slab);
+        inner.position.set(1, 0, 1);
+        root.add(inner);
+        root.position.set(3, 0, 3);
+        root.updateMatrixWorld(true);
+        const out = { surfaceRoot: null };
+        const p = computeDropPoint(new Raycaster(), groundCam(), new Set([root]), rect, 400, 300, out);
+        // 命中点在 (4, 2, 4)(分组偏移叠出来了),回填的是登记根本身
+        expect(p.y).toBeCloseTo(2, 6);
+        expect(out.surfaceRoot).toBe(root);
+    });
+    it('地面兜底时 out.surfaceRoot 为 null', () => {
+        const out = { surfaceRoot: null };
+        computeDropPoint(new Raycaster(), groundCam(), new Set(), rect, 400, 300, out);
+        expect(out.surfaceRoot).toBeNull();
+    });
+});
+describe('computeViewPlanePoint', () => {
+    // 斜视相机在 (0,10,20) 看向原点,锚点取原点(深度≈22.4)
+    const anchor = new Vector3(0, 0, 0);
+    it('落点恒在过锚点的视平面上(与视线垂直)', () => {
+        const cam = groundCam();
+        const forward = cam.getWorldDirection(new Vector3());
+        for (const [x, y] of [
+            [400, 300],
+            [200, 150],
+            [600, 450],
+        ]) {
+            const p = computeViewPlanePoint(new Raycaster(), cam, rect, x, y, anchor);
+            expect(p).not.toBeNull();
+            expect(p.clone().sub(anchor).dot(forward)).toBeCloseTo(0, 6);
+        }
+    });
+    it('指针上移 = 世界升高,下移 = 降低(Blender G 默认手感)', () => {
+        const cam = groundCam();
+        const up = computeViewPlanePoint(new Raycaster(), cam, rect, 400, 100, anchor);
+        const mid = computeViewPlanePoint(new Raycaster(), cam, rect, 400, 300, anchor);
+        const down = computeViewPlanePoint(new Raycaster(), cam, rect, 400, 500, anchor);
+        expect(up.y).toBeGreaterThan(mid.y);
+        expect(down.y).toBeLessThan(mid.y);
+    });
+    it('顶视时退化为水平面:任意指针位置 y 恒等于锚点 y', () => {
+        const c = new PerspectiveCamera(50, 800 / 600, 0.1, 1000);
+        c.position.set(0, 20, 0.001); // 近乎正上方(完全 0 会让 lookAt 退化)
+        c.lookAt(0, 0, 0);
+        c.updateMatrixWorld();
+        const a = new Vector3(0, 5, 0);
+        for (const [x, y] of [
+            [400, 300],
+            [100, 100],
+            [700, 500],
+        ]) {
+            // 相机带了 0.001 的防退化偏移,平面略微倾斜,精度放到毫米级
+            const p = computeViewPlanePoint(new Raycaster(), c, rect, x, y, a);
+            expect(p.y).toBeCloseTo(5, 2);
+        }
+    });
+});
+describe('computeVerticalConstraintPoint', () => {
+    // 斜视相机,基准点 (3, 2, -4):竖直约束 = 锁定 x/z,只动 y
+    const base = new Vector3(3, 2, -4);
+    it('锁定基准点的 x/z,指针上下移动只改变 y', () => {
+        const cam = groundCam();
+        const up = computeVerticalConstraintPoint(new Raycaster(), cam, rect, 400, 100, base);
+        const mid = computeVerticalConstraintPoint(new Raycaster(), cam, rect, 400, 300, base);
+        const down = computeVerticalConstraintPoint(new Raycaster(), cam, rect, 400, 500, base);
+        for (const p of [up, mid, down]) {
+            expect(p.x).toBeCloseTo(3, 6);
+            expect(p.z).toBeCloseTo(-4, 6);
+        }
+        expect(up.y).toBeGreaterThan(mid.y);
+        expect(down.y).toBeLessThan(mid.y);
+    });
+    it('指针正对基准点时 y ≈ 基准 y', () => {
+        const cam = groundCam();
+        cam.lookAt(base); // 中心射线穿过基准点
+        cam.updateMatrixWorld();
+        const p = computeVerticalConstraintPoint(new Raycaster(), cam, rect, 400, 300, base);
+        expect(p.y).toBeCloseTo(2, 4);
+    });
+    it('视线与竖直轴平行(正顶视)时返回 null', () => {
+        const c = new PerspectiveCamera(50, 800 / 600, 0.1, 1000);
+        c.position.set(3, 20, -4); // 正好在基准点正上方
+        c.lookAt(base);
+        c.updateMatrixWorld();
+        expect(computeVerticalConstraintPoint(new Raycaster(), c, rect, 400, 300, base)).toBeNull();
+    });
+});
+describe('computeHorizontalConstraintPoint', () => {
+    const base = new Vector3(3, 2, -4);
+    it('锁定基准高度:任意指针位置 y 恒等于基准 y,x/z 跟随指针', () => {
+        const cam = groundCam();
+        const ps = [
+            [400, 300],
+            [200, 400],
+            [600, 200],
+        ].map(([x, y]) => computeHorizontalConstraintPoint(new Raycaster(), cam, rect, x, y, base));
+        for (const p of ps)
+            expect(p).not.toBeNull();
+        for (const p of ps)
+            expect(p.y).toBeCloseTo(2, 6);
+        // 指针位置不同,水平落点确实不同(不是钉死在一个点)
+        expect(ps[0].distanceTo(ps[1])).toBeGreaterThan(0.5);
+        expect(ps[0].distanceTo(ps[2])).toBeGreaterThan(0.5);
+    });
+});

package/dist/editorOnly.d.ts

@@ -0,0 +1,6 @@
+import type { Object3D } from 'three';
+/** 登记一个编辑辅助对象,返回注销函数(卸载时调用) */
+export declare function registerEditorOnly(obj: Object3D): () => void;
+/** 隐藏全部编辑辅助对象后执行 fn(如同 gl.render),结束后恢复 */
+export declare function withEditorOnlyHidden<T>(fn: () => T): T;
+//# sourceMappingURL=editorOnly.d.ts.map

package/dist/editorOnly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editorOnly.d.ts","sourceRoot":"","sources":["../src/editorOnly.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,OAAO,CAAA;AAanC,+BAA+B;AAC/B,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,IAAI,CAK5D;AAED,2CAA2C;AAC3C,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAWtD"}

package/dist/editorOnly.js

@@ -0,0 +1,32 @@
+/**
+ * 只在编辑视角出现、不进镜头取景的对象登记表(镜头视锥线、瞄准点手柄、
+ * 选中箭头等)。画中画/镜头视角渲染时统一隐藏,保证取景画面干净——
+ * Blender 的镜头视图同样不画这些辅助对象。
+ *
+ * 不用 three 的 layers 实现:Raycaster 默认只测 layer 0,把辅助对象挪到
+ * 别的层会让点选/拖拽失效,还要逐个改射线器,代价比"渲染前后切 visible"
+ * 大得多。
+ */
+const editorOnlyObjects = new Set();
+/** 登记一个编辑辅助对象,返回注销函数(卸载时调用) */
+export function registerEditorOnly(obj) {
+    editorOnlyObjects.add(obj);
+    return () => {
+        editorOnlyObjects.delete(obj);
+    };
+}
+/** 隐藏全部编辑辅助对象后执行 fn(如同 gl.render),结束后恢复 */
+export function withEditorOnlyHidden(fn) {
+    const saved = [];
+    for (const obj of editorOnlyObjects) {
+        saved.push({ obj, visible: obj.visible });
+        obj.visible = false;
+    }
+    try {
+        return fn();
+    }
+    finally {
+        for (const { obj, visible } of saved)
+            obj.visible = visible;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 宿主错误提示接口(2026-10-16):模块不内置错误条,统一把可展示错误
+ * 转成这个形状交给宿主,由宿主自己的提示组件渲染。
+ */
+import type { LibraryError, LibraryErrorCode } from './assetLibrary/source';
+/** library = 资产库存储/启动清理;export = 视频导出 */
+export type CameraStudioErrorSource = 'library' | 'export';
+/** 宿主提示组件可直接渲染的结构化错误 */
+export type CameraStudioError = {
+    source: CameraStudioErrorSource;
+    /** LibraryError 六码;非库错误当前一律 unknown */
+    code: LibraryErrorCode;
+    /** 可直接给宿主提示组件展示的文本 */
+    message: string;
+    /** 原始错误(供宿主日志/排错;未知错误原样带上) */
+    cause?: unknown;
+};
+/** CameraStudioConfig.onError 的回调签名 */
+export type CameraStudioErrorHandler = (error: CameraStudioError) => void;
+/** 聚合库上告的 LibraryError → 宿主错误形状(保留六码与原始 cause) */
+export declare function cameraErrorFromLibrary(error: LibraryError): CameraStudioError;
+/** 启动清理等非 LibraryError 失败 → 宿主错误形状(操作名进 message) */
+export declare function cameraErrorFromUnknown(source: CameraStudioErrorSource, message: string, cause?: unknown): CameraStudioError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAC,YAAY,EAAE,gBAAgB,EAAC,MAAM,uBAAuB,CAAA;AAEzE,yCAAyC;AACzC,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE1D,wBAAwB;AACxB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,uBAAuB,CAAA;IAC/B,uCAAuC;IACvC,IAAI,EAAE,gBAAgB,CAAA;IACtB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,8BAA8B;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAED,uCAAuC;AACvC,MAAM,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;AAEzE,kDAAkD;AAClD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,YAAY,GAAG,iBAAiB,CAO7E;AAED,oDAAoD;AACpD,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,uBAAuB,EAC/B,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,GACd,iBAAiB,CAEnB"}

package/dist/errors.js

@@ -0,0 +1,13 @@
+/** 聚合库上告的 LibraryError → 宿主错误形状(保留六码与原始 cause) */
+export function cameraErrorFromLibrary(error) {
+    return {
+        source: 'library',
+        code: error.code,
+        message: error.message,
+        cause: error.cause ?? error,
+    };
+}
+/** 启动清理等非 LibraryError 失败 → 宿主错误形状(操作名进 message) */
+export function cameraErrorFromUnknown(source, message, cause) {
+    return { source, code: 'unknown', message, cause };
+}

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/dist/gestureProps.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 手势属性(2026-10-05,左手势/右手势):姿势属性的「纯选择」版——
+ * 值只能是库手势引用或「无手势」,没有自定义快照入口(不挂姿势模式);
+ * 可打帧(复用姿势插值器,帧间手指平滑过渡)。
+ *
+ * 应用语义 = 叠加层:姿势层(全身,含手指)先写,手势层后写且只写本侧
+ * 手指骨——身体与另一只手绝不被手势触碰;清掉手势后手指由姿势层
+ * (或绑定姿势)自然归位,因为应用链每次都先整写姿势层。
+ *
+ * 手势条目判定按数据形状:bones 全是手指骨(不含手腕/躯干)的库姿势。
+ * 注意 QBX 手势条目左右手骨都带(未动侧是 rest 方向),所以分两层过滤:
+ *   列表:按名字侧(「· 左手/· 右手」后缀;无后缀 = 双手手势,两侧都列)
+ *   应用:按骨名 Left/Right 侧过滤,只写本侧 15 根手指骨
+ * 列表管 UX,骨过滤管正确性,各管各的。
+ *
+ * 姿势选择框与手势选择框的分家也走 isHandPoseEntry:手势条目只进手势
+ * 框,姿势框回归纯身体姿势(2026-10-05 与用户对齐)。
+ */
+import type { PoseEntry } from './assetLibrary/types';
+import type { PoseBones } from './poseMode/poseOverride';
+import { poseInterpolate } from './poseMode/poseInterpolate';
+export type GestureSide = 'left' | 'right';
+export declare function isFingerBoneName(name: string): boolean;
+/** 手势条目判定:非空且每根骨都是手指骨(全身姿势含躯干骨,天然排除) */
+export declare function isHandPoseEntry(entry: {
+    bones?: PoseBones;
+}): boolean;
+/** 应用侧过滤:只留本侧手指骨(条目里另一侧的 rest 手指骨被裁掉) */
+export declare function filterGestureBonesBySide(bones: PoseBones, side: GestureSide): PoseBones;
+/** 条目名字侧:「· 左手/· 右手」后缀;无后缀 = 双手手势 */
+export declare function gestureEntryNameSide(name: string): GestureSide | null;
+/**
+ * 解析手势值 → 本侧手指骨(应用层的唯一入口)。
+ * 空值/解析不出/该侧无骨 → null(跳过应用,手指保持姿势层状态)。
+ * 求值产物可能是 custom 快照(打帧插值),parse/resolve 通吃,无需特判。
+ */
+export declare function resolveGestureBones(gestureJson: string, side: GestureSide): PoseBones | null;
+/** 手势属性的注册形态:与姿势同构(string + 编辑器 key + 自定义插值器),
+ *  但编辑器只给选择(无手势/库手势),没有自定义入口 */
+export declare function gesturePropConfigShape(side: GestureSide): {
+    defaultValue: string;
+    opts: {
+        label: () => string;
+        editor: string;
+        interpolate: typeof poseInterpolate;
+    };
+};
+export type GestureOptionKey = 'none' | `lib:${string}`;
+export type GestureOption = {
+    key: GestureOptionKey;
+    label: string;
+    disabled?: boolean;
+    hint?: string;
+    /** 缩略图 URL(条目带 thumbnailId 且解析完成时由调用方注入) */
+    thumbUrl?: string;
+};
+/**
+ * 手势选择框选项:「无手势」永远第一项;往下是本侧(或双手)手势条目,
+ * 异族置灰。当前值引用已删条目时追加置灰缺失项如实显示。
+ * 值本不该是 custom(无自定义入口),但打帧插值产物/手工粘贴可能出现——
+ * current 如实报 'custom'(列表无对应高亮项,与姿势框同处理)。
+ */
+export declare function buildGestureOptions(args: {
+    gestureJson: string;
+    libEntries: Pick<PoseEntry, 'id' | 'name' | 'rig' | 'bones' | 'thumbnailId'>[];
+    side: GestureSide;
+    /** 当前选中模型的骨架族;缺省=不过滤 */
+    selectedRig?: string;
+    /** 缩略图 URL 解析(懒加载 hook 的 getThumbUrl);缺省=无图 */
+    thumbUrlOf?: (entry: {
+        id: string;
+        thumbnailId?: string;
+    }) => string | undefined;
+    /** 「无手势」项的缩略图(2026-10-05):调用方传本侧「基础·放松」条目的
+        预览图——放松手就是无叠加手势的样子,语义正好 */
+    noneThumbUrl?: string;
+    /** 显示名解析(poseEntryName:种子条目查 i18n 词典);缺省=条目名原文 */
+    nameOf?: (entry: {
+        id: string;
+        name: string;
+    }) => string;
+    t: (k: string) => string;
+}): {
+    options: GestureOption[];
+    current: GestureOptionKey | 'custom';
+};
+/** 手势属性行值区域显示文本:空值「无手势」;库引用 → 条目名(缺失带标记);
+ *  custom(打帧插值产物/手工粘贴,本编辑器不产生)→ 自定义姿势 */
+export declare function gestureDisplayText(args: {
+    gestureJson: string;
+    libEntries: Pick<PoseEntry, 'id' | 'name'>[];
+    /** 显示名解析(poseEntryName:种子条目查 i18n 词典);缺省=条目名原文 */
+    nameOf?: (entry: {
+        id: string;
+        name: string;
+    }) => string;
+    t: (k: string) => string;
+}): string;
+//# sourceMappingURL=gestureProps.d.ts.map

package/dist/gestureProps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gestureProps.d.ts","sourceRoot":"","sources":["../src/gestureProps.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yBAAyB,CAAA;AAEtD,OAAO,EAAC,eAAe,EAAC,MAAM,4BAA4B,CAAA;AAI1D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,CAAA;AAS1C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wCAAwC;AACxC,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAAG,OAAO,CAGnE;AAED,yCAAyC;AACzC,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,WAAW,GAChB,SAAS,CAKX;AAED,qCAAqC;AACrC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAIrE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,WAAW,GAChB,SAAS,GAAG,IAAI,CAKlB;AAED;gCACgC;AAChC,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG;IACzD,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,MAAM,CAAA;QACnB,MAAM,EAAE,MAAM,CAAA;QACd,WAAW,EAAE,OAAO,eAAe,CAAA;KACpC,CAAA;CACF,CAUA;AAID,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,MAAM,EAAE,CAAA;AAEvD,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,gBAAgB,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,aAAa,CAAC,EAAE,CAAA;IAC9E,IAAI,EAAE,WAAW,CAAA;IACjB,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,MAAM,GAAG,SAAS,CAAA;IAC9E;kCAC8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kDAAkD;IAClD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,KAAK,MAAM,CAAA;IACtD,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CACzB,GAAG;IAAC,OAAO,EAAE,aAAa,EAAE,CAAC;IAAC,OAAO,EAAE,gBAAgB,GAAG,QAAQ,CAAA;CAAC,CAkDnE;AAED;yCACyC;AACzC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC,EAAE,CAAA;IAC5C,kDAAkD;IAClD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,KAAK,MAAM,CAAA;IACtD,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CACzB,GAAG,MAAM,CAST"}