@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/assetLibrary/thumbnail.d.ts

@@ -0,0 +1,14 @@
+import type { ImportItem } from './importPipeline';
+import type { Library } from './library';
+/**
+ * 离屏渲染模型缩略图(128×128 PNG)。WebGL 上下文创建失败、
+ * 解析失败等情况一律返回 undefined,调用方降级为图标占位。
+ */
+export declare function renderThumbnail(glb: ArrayBuffer): Promise<Blob | undefined>;
+/**
+ * 给导入成功的 model 项补缩略图:按 contentHash 找回刚入库、
+ * 还没有 thumbnailId 的条目逐个渲染。手动导入与内置播种共用。
+ * WebGL 不可用时 renderThumbnail 返回 undefined,自然降级为占位图标。
+ */
+export declare function backfillModelThumbnails(items: ImportItem[], library: Library): Promise<void>;
+//# sourceMappingURL=thumbnail.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/thumbnail.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAA;AAChD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,WAAW,CAAA;AAGtC;;;GAGG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAmD3B;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,IAAI,CAAC,CAgBf"}

package/dist/assetLibrary/thumbnail.js

@@ -0,0 +1,70 @@
+import { AmbientLight, Box3, DirectionalLight, PerspectiveCamera, Scene, Sphere, Vector3, WebGLRenderer, } from 'three';
+import { createGLTFLoader } from './gltfLoader';
+/**
+ * 离屏渲染模型缩略图(128×128 PNG)。WebGL 上下文创建失败、
+ * 解析失败等情况一律返回 undefined,调用方降级为图标占位。
+ */
+export async function renderThumbnail(glb) {
+    try {
+        const canvas = document.createElement('canvas');
+        canvas.width = 128;
+        canvas.height = 128;
+        const renderer = new WebGLRenderer({
+            canvas,
+            antialias: true,
+            preserveDrawingBuffer: true,
+            alpha: true,
+        });
+        try {
+            const scene = new Scene();
+            scene.add(new AmbientLight(0xffffff, 1.4));
+            const dir = new DirectionalLight(0xffffff, 1.6);
+            dir.position.set(3, 5, 4);
+            scene.add(dir);
+            const gltf = await new Promise((resolve, reject) => createGLTFLoader().parse(glb, '', resolve, reject));
+            scene.add(gltf.scene);
+            const box = new Box3().setFromObject(gltf.scene);
+            const sphere = box.getBoundingSphere(new Sphere());
+            const radius = sphere.radius || 1;
+            // 取景距离按包围球 + 垂直视场角算,保证整个模型(高瘦的人形
+            // 尤其容易顶天)都进画面,再留 15% 呼吸边距
+            const fov = 40;
+            const distance = (radius / Math.tan(((fov / 2) * Math.PI) / 180)) * 1.15;
+            const camera = new PerspectiveCamera(fov, 1, distance / 100, distance * 10);
+            camera.position
+                .copy(sphere.center)
+                .add(new Vector3(0.7, 0.5, 0.7).normalize().multiplyScalar(distance));
+            camera.lookAt(sphere.center);
+            renderer.render(scene, camera);
+            return await new Promise((resolve) => canvas.toBlob((b) => resolve(b ?? undefined), 'image/png'));
+        }
+        finally {
+            renderer.dispose();
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 给导入成功的 model 项补缩略图:按 contentHash 找回刚入库、
+ * 还没有 thumbnailId 的条目逐个渲染。手动导入与内置播种共用。
+ * WebGL 不可用时 renderThumbnail 返回 undefined,自然降级为占位图标。
+ */
+export async function backfillModelThumbnails(items, library) {
+    for (const item of items) {
+        if (item.type !== 'model')
+            continue;
+        const blob = await renderThumbnail(item.glb);
+        if (!blob)
+            continue;
+        const list = (await library.listEntries('model'));
+        const entry = list.find((e) => e.contentHash === item.contentHash && !e.thumbnailId);
+        if (entry) {
+            await library.putBlobWithEntry(blob, (thumbnailId) => ({
+                ...entry,
+                thumbnailId,
+            }));
+        }
+    }
+}

package/dist/assetLibrary/types.d.ts

@@ -0,0 +1,54 @@
+import type { WritableLibrarySource } from './source';
+/** 骨架族 id(rigIdOf 生成);无骨架模型为 'static' */
+export type RigId = string;
+/** 骨架族别名:给人看的名字,面板骨架标签显示 */
+export type RigAlias = {
+    rig: RigId;
+    name: string;
+};
+export type EntryKind = 'model' | 'pose' | 'animation';
+export type ModelEntry = {
+    id: string;
+    kind: 'model';
+    name: string;
+    rig: RigId;
+    blobId: string;
+    contentHash: string;
+    thumbnailId?: string;
+    boneCount: number;
+    vertexCount: number;
+    createdAt: number;
+};
+export type PoseEntry = {
+    id: string;
+    kind: 'pose';
+    name: string;
+    rig: RigId;
+    /** 缩略图 blob id(QBX 手势:源包内嵌预览图,管线期导出随包播种) */
+    thumbnailId?: string;
+    bones: Record<string, {
+        rotation?: [number, number, number, number];
+        position?: [number, number, number];
+    }>;
+    createdAt: number;
+};
+export type AnimationEntry = {
+    id: string;
+    kind: 'animation';
+    name: string;
+    rig: RigId;
+    blobId: string;
+    contentHash: string;
+    duration: number;
+    createdAt: number;
+};
+export type LibraryEntry = ModelEntry | PoseEntry | AnimationEntry;
+/**
+ * 库的存储适配接口:playground 用 IndexedDB 实现,应用层可换 HTTP
+ * 实现。大二进制以 URL 形式暴露(本地 blob: / 远程 CDN 地址),
+ * blobId = 内容哈希,天然支持去重。
+ *
+ * @deprecated 统一数据源后的兼容别名,新代码用 WritableLibrarySource
+ */
+export type LibraryBackend = WritableLibrarySource;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,UAAU,CAAA;AAEnD,yCAAyC;AACzC,MAAM,MAAM,KAAK,GAAG,MAAM,CAAA;AAE1B,4BAA4B;AAC5B,MAAM,MAAM,QAAQ,GAAG;IAAC,GAAG,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAA;AAEjD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAAA;AAEtD,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,KAAK,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,KAAK,CAAA;IACV,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,MAAM,CACX,MAAM,EACN;QACE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;QAC3C,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;KACpC,CACF,CAAA;IACD,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,WAAW,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,KAAK,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,cAAc,CAAA;AAElE;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAA"}

package/dist/assetLibrary/types.js

@@ -0,0 +1 @@
+export {};

package/dist/assetLibrary/useModelThumbUrl.d.ts

@@ -0,0 +1,10 @@
+/** 结构只要 id + thumbnailId:模型/姿势条目都满足 */
+export type ThumbEntry = {
+    id: string;
+    thumbnailId?: string;
+};
+export declare function useModelThumbUrl(): {
+    getThumbUrl: (entry: ThumbEntry) => string | undefined;
+    dropThumbUrl: (id: string) => void;
+};
+//# sourceMappingURL=useModelThumbUrl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useModelThumbUrl.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/useModelThumbUrl.ts"],"names":[],"mappings":"AAeA,uCAAuC;AACvC,MAAM,MAAM,UAAU,GAAG;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAC,CAAA;AAE3D,wBAAgB,gBAAgB,IAAI;IAClC,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,GAAG,SAAS,CAAA;IACtD,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CACnC,CAwCA"}

package/dist/assetLibrary/useModelThumbUrl.js

@@ -0,0 +1,56 @@
+// packages/camera-studio/src/assetLibrary/useModelThumbUrl.ts
+/**
+ * 缩略图懒加载 hook:从 AssetLibraryPanel 抽出(2026-10-01 注册制改造),
+ * 内置模型框体与注册进站的宿主模型框体(ModelPickerProps.getThumbUrl)共用;
+ * 2026-10-05 起姿势/手势选择框也用它(姿势条目的 QBX 预览图)。
+ *
+ * 用法:卡片渲染时调 getThumbUrl——命中缓存直接给 URL;未命中触发异步
+ * 加载并先返回 undefined,加载完成 setState 触发重渲后命中。并发同一
+ * 条目只发一次 getBlobUrl;URL 生命周期由后端 session 级缓存管理,这里
+ * 不在卸载时 revoke,避免其他消费者拿到失效地址。dropThumbUrl 供删除
+ * 条目后清掉该条缓存。
+ */
+import { useEffect, useRef, useState } from 'react';
+import { getLibrary } from './library';
+export function useModelThumbUrl() {
+    const [thumbUrls, setThumbUrls] = useState({});
+    // 防止同一缩略图并发多次 getBlobUrl
+    const loadingRef = useRef(new Set());
+    // 卸载后丢弃迟到的加载结果,不写已卸载组件的 state
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    const getThumbUrl = (entry) => {
+        if (!entry.thumbnailId)
+            return undefined;
+        const cached = thumbUrls[entry.id];
+        if (cached)
+            return cached;
+        if (loadingRef.current.has(entry.id))
+            return undefined;
+        loadingRef.current.add(entry.id);
+        void getLibrary()
+            .getBlobUrl(entry.thumbnailId)
+            .then((url) => {
+            loadingRef.current.delete(entry.id);
+            if (!mountedRef.current)
+                return;
+            setThumbUrls((m) => ({ ...m, [entry.id]: url }));
+        })
+            .catch(() => {
+            loadingRef.current.delete(entry.id);
+        });
+        return undefined;
+    };
+    const dropThumbUrl = (id) => {
+        setThumbUrls((m) => {
+            const { [id]: _, ...rest } = m;
+            return rest;
+        });
+    };
+    return { getThumbUrl, dropThumbUrl };
+}

package/dist/boneAnchorWiring.test.d.ts

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

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

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

package/dist/boneAnchorWiring.test.js

@@ -0,0 +1,173 @@
+/**
+ * 骨骼锚点接线回归(终审修复波沉淀):放置实例登记后的整条数据链
+ * + 目标登记表广播 + 幂等守卫。
+ *
+ * 覆盖(对应终审 Important-1/Important-2 的行为规格):
+ *  - registerBoneAnchors → 相机「瞄准目标」/锚点「父级」两个下拉出现
+ *    6 个骨骼项(en/zh 部位名)→ resolveAimTarget/resolveAnchorParent
+ *    命中骨骼节点 → unregister 后选项与解析同时消失;
+ *  - 骨架完全不认识的模型自然落空(不进 bone: 选项,非错误);
+ *  - 四条登记路径的广播:subscribeTargetRegistry 能收到骨骼锚点
+ *    (register/unregisterBoneAnchors)与放置实例
+ *    (register/unregisterPlacedInstance)的登记通知;
+ *  - 幂等守卫:同 placementKey 同根重复登记不重建节点(保住已绑定
+ *    锚点网格的场景树身份);换根才重建;注销后再登记允许重建。
+ */
+import { Bone, Group, Object3D } from 'three';
+import { setLanguage, translate } from '@dreamerbird/studio/i18n';
+import { registerBoneAnchors, unregisterBoneAnchors, getBoneAnchorObjects, } from './boneAnchors';
+import { aimTargetOptions, anchorParentOptionsFor, resolveAimTarget, resolveAnchorParent, setAimOptionsSheet, subscribeTargetRegistry, } from './aimTargets';
+import { registerPlacedInstance, unregisterPlacedInstance, getPlacedInstances, } from './PlacementManager';
+import { en, zhCN } from './i18n';
+const PLACEMENT_KEY = 'Models / Y Bot';
+const BONE_IDS = [
+    'bone:Models / Y Bot#head',
+    'bone:Models / Y Bot#chest',
+    'bone:Models / Y Bot#handL',
+    'bone:Models / Y Bot#handR',
+    'bone:Models / Y Bot#legL',
+    'bone:Models / Y Bot#legR',
+];
+function makeSkeleton() {
+    const root = new Object3D();
+    const mk = (name, parent) => {
+        const b = new Bone();
+        b.name = name;
+        parent.add(b);
+        return b;
+    };
+    const hips = mk('mixamorigHips', root);
+    const spine = mk('mixamorigSpine', hips);
+    const spine1 = mk('mixamorigSpine1', spine);
+    mk('mixamorigSpine2', spine1);
+    const head = mk('mixamorigHead', spine1);
+    const handL = mk('mixamorigLeftHand', spine1);
+    const handR = mk('mixamorigRightHand', spine1);
+    const legL = mk('mixamorigLeftLeg', hips);
+    const legR = mk('mixamorigRightLeg', hips);
+    return { root, head, handL, handR, legL, legR };
+}
+function stubSheet(placementsJson) {
+    const registries = {};
+    return {
+        object(key) {
+            if (!registries[key]) {
+                const json = key === 'Placements' ? placementsJson : '[]';
+                registries[key] = {
+                    props: { list: json },
+                    value: { list: json },
+                    onValuesChange: () => () => { },
+                };
+            }
+            return registries[key];
+        },
+    };
+}
+const PLACEMENTS = JSON.stringify([
+    { key: PLACEMENT_KEY, position: { x: 0, y: 0, z: 0 } },
+]);
+describe('骨骼锚点接线(终审 Important-1/2 回归)', () => {
+    beforeAll(() => {
+        setLanguage('en');
+    });
+    afterAll(() => {
+        setLanguage('en');
+    });
+    test('登记后两个下拉出现「Y Bot · 部位」6 项;解析命中骨骼节点;注销后消失', () => {
+        const { root, head, handL } = makeSkeleton();
+        registerBoneAnchors(PLACEMENT_KEY, root);
+        // 1) 运行时 boneAnchors 表:6 项,挂对骨骼
+        const anchors = getBoneAnchorObjects();
+        expect([...anchors.keys()].sort()).toEqual([...BONE_IDS].sort());
+        expect(anchors.get('bone:Models / Y Bot#head').parent).toBe(head);
+        expect(anchors.get('bone:Models / Y Bot#handL').parent).toBe(handL);
+        // 2) 相机「瞄准目标」下拉:6 个骨骼项,英文部位名,模型显示名去前缀
+        setAimOptionsSheet(stubSheet(PLACEMENTS));
+        const aim = aimTargetOptions();
+        for (const id of BONE_IDS)
+            expect(aim).toHaveProperty(id);
+        expect(aim['bone:Models / Y Bot#head']).toBe('Y Bot · Head');
+        expect(aim['bone:Models / Y Bot#handR']).toBe('Y Bot · Right hand');
+        // 3) 锚点「父级」下拉同样 6 项
+        const parentOpts = anchorParentOptionsFor('Anchor 1');
+        for (const id of BONE_IDS)
+            expect(parentOpts).toHaveProperty(id);
+        expect(parentOpts['bone:Models / Y Bot#chest']).toBe('Y Bot · Chest');
+        // 4) 帧驱动解析:瞄准/父级都能拿到骨骼下的锚点节点
+        expect(resolveAimTarget('bone:Models / Y Bot#head')).toBe(anchors.get('bone:Models / Y Bot#head'));
+        expect(resolveAnchorParent('bone:Models / Y Bot#handL')).toBe(anchors.get('bone:Models / Y Bot#handL'));
+        // 5) 中文部位名
+        setLanguage('zh-CN');
+        expect(aimTargetOptions()['bone:Models / Y Bot#head']).toBe('Y Bot · 头');
+        expect(aimTargetOptions()['bone:Models / Y Bot#chest']).toBe('Y Bot · 胸口');
+        expect(anchorParentOptionsFor('Anchor 1')['bone:Models / Y Bot#legR']).toBe('Y Bot · 右腿');
+        setLanguage('en');
+        // 6) 注销(删模型/卸载):选项与解析同时消失
+        unregisterBoneAnchors(PLACEMENT_KEY);
+        expect(getBoneAnchorObjects().size).toBe(0);
+        const aimAfter = aimTargetOptions();
+        for (const id of BONE_IDS)
+            expect(aimAfter).not.toHaveProperty(id);
+        expect(resolveAimTarget('bone:Models / Y Bot#head')).toBeNull();
+        expect(resolveAnchorParent('bone:Models / Y Bot#handL')).toBeNull();
+    });
+    test('骨架完全不认识的模型:自然落空,不出现在选项里(正常行为非错误)', () => {
+        const meshOnly = new Object3D();
+        meshOnly.add(new Bone()); // 无名骨骼
+        registerBoneAnchors('Models / Rock', meshOnly);
+        expect(getBoneAnchorObjects().size).toBe(0);
+        const aim = aimTargetOptions();
+        expect(Object.keys(aim).filter((k) => k.startsWith('bone:'))).toEqual([]);
+        unregisterBoneAnchors('Models / Rock');
+    });
+    test('放置实例登记/注销经 subscribeTargetRegistry 广播;骨骼登记的幂等重跑静默', () => {
+        const { root } = makeSkeleton();
+        const instance = new Group();
+        const calls = [];
+        const unsub = subscribeTargetRegistry(() => calls.push('notify'));
+        // bones 的广播挂在 PlacementManager 的登记 effect 上(纯函数层不广播);
+        // 这里验证的是:boneAnchors 登记本身不偷跑广播——幂等守卫的 effect
+        // 重跑(注册表增删任一模型)才不会让 ShotCamera/Anchors 空刷重渲染
+        registerBoneAnchors(PLACEMENT_KEY, root);
+        registerBoneAnchors(PLACEMENT_KEY, root); // 幂等短路,静默
+        unregisterBoneAnchors(PLACEMENT_KEY);
+        // placedInstances 的广播在 register/unregisterPlacedInstance 本体
+        // (usePlacedInstance 委托它们),订阅方按序收到登记与注销各一次
+        registerPlacedInstance(PLACEMENT_KEY, instance);
+        unregisterPlacedInstance(PLACEMENT_KEY);
+        unsub();
+        expect(calls).toEqual(['notify', 'notify']);
+        expect(getPlacedInstances().size).toBe(0);
+    });
+    test('幂等守卫:同根重复登记不重建节点;换根才重建;注销后再登记允许重建', () => {
+        const { root, head } = makeSkeleton();
+        const headId = 'bone:Models / Y Bot#head';
+        registerBoneAnchors(PLACEMENT_KEY, root);
+        const first = getBoneAnchorObjects().get(headId);
+        expect(first.parent).toBe(head);
+        // 同根重复登记(放置注册表增删任一模型 → 所有登记 effect 重跑的场景)
+        // 必须保持节点身份,绑在骨骼锚点上的锚点网格才不会脱离场景树
+        registerBoneAnchors(PLACEMENT_KEY, root);
+        expect(getBoneAnchorObjects().get(headId)).toBe(first);
+        expect(getBoneAnchorObjects().size).toBe(6);
+        // 换根(热更新/实例重建)才允许重建
+        const { root: root2 } = makeSkeleton();
+        registerBoneAnchors(PLACEMENT_KEY, root2);
+        const second = getBoneAnchorObjects().get(headId);
+        expect(second).not.toBe(first);
+        // 注销清记录:同根再登记是全新节点(不复用旧身份)
+        unregisterBoneAnchors(PLACEMENT_KEY);
+        registerBoneAnchors(PLACEMENT_KEY, root2);
+        expect(getBoneAnchorObjects().get(headId)).not.toBe(second);
+        unregisterBoneAnchors(PLACEMENT_KEY);
+    });
+    test('六个部位词条 en/zh-CN 齐且不回退 key', () => {
+        for (const part of ['head', 'chest', 'handL', 'handR', 'legL', 'legR']) {
+            const key = `pg.parts.${part}`;
+            // 注意:jest toHaveProperty 按 . 分路径,带点的 key 用 hasOwnProperty
+            expect(Object.prototype.hasOwnProperty.call(en, key)).toBe(true);
+            expect(Object.prototype.hasOwnProperty.call(zhCN, key)).toBe(true);
+            expect(translate(key)).toBe(en[key]);
+        }
+    });
+});

package/dist/boneAnchors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 骨骼锚点:放置模型的"可瞄准部位"。按骨骼名在实例骨架里找
+ * 头/胸口/双手/双腿,把无网格的 Object3D 挂到骨骼下(对齐 Blender
+ * 空物体的"骨骼父子"),登记进模块级 Map 供瞄准/父级绑定解析。
+ * 运行时零件,不进大纲、无属性面板。
+ */
+import type { Object3D } from 'three';
+export declare const BONE_PARTS: readonly ["head", "chest", "handL", "handR", "legL", "legR"];
+export type BonePart = (typeof BONE_PARTS)[number];
+/** 归一化骨骼名:去 mixamorig 前缀/冒号、去下划线、转小写。
+ *  "mixamorig:Head" / "Mixamorig_Head" / "Head" → "head" */
+export declare function normalizeBoneName(name: string): string;
+/** 在骨架树里按部位找骨骼;找不到的部位缺省(Y Bot 实测
+ * 骨架前缀是 mixamorig、无冒号,归一化后天然兼容) */
+export declare function resolveAnchorBones(root: Object3D): Partial<Record<BonePart, Object3D>>;
+export declare function makeBoneAnchorId(placementKey: string, part: BonePart): string;
+export declare function parseBoneAnchorId(id: string): {
+    placementKey: string;
+    part: BonePart;
+} | null;
+/**
+ * 在放置实例上登记骨骼锚点:解析部位 → 挂节点 → 入表。
+ * 同 placementKey 重复调用先清旧组(热更新/重挂载防堆积);
+ * 同根重复调用(注册表增删导致的 effect 重跑)保持节点身份不重建。
+ * 无骨骼的模型自然解析为空,不进表。
+ */
+export declare function registerBoneAnchors(placementKey: string, root: Object3D): void;
+export declare function unregisterBoneAnchors(placementKey: string): void;
+export declare function getBoneAnchorObjects(): ReadonlyMap<string, Object3D>;
+//# sourceMappingURL=boneAnchors.d.ts.map

package/dist/boneAnchors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boneAnchors.d.ts","sourceRoot":"","sources":["../src/boneAnchors.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AACH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,OAAO,CAAA;AAGnC,eAAO,MAAM,UAAU,8DAOb,CAAA;AACV,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAalD;4DAC4D;AAC5D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED;mCACmC;AACnC,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAqBrC;AAED,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAE7E;AAED,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,MAAM,GACT;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,GAAG,IAAI,CAS/C;AAWD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,QAAQ,GACb,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAUhE;AAED,wBAAgB,oBAAoB,IAAI,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAEpE"}

package/dist/boneAnchors.js

@@ -0,0 +1,111 @@
+import { Object3D as Object3DImpl } from 'three';
+export const BONE_PARTS = [
+    'head',
+    'chest',
+    'handL',
+    'handR',
+    'legL',
+    'legR',
+];
+/** 部位的骨骼名候选(按优先序);匹配前先做归一化 */
+const BONE_CANDIDATES = {
+    head: ['Head'],
+    // 胸口取中段脊柱(Spine1);Spine2 更靠脖颈,作兜底
+    chest: ['Spine1', 'Spine2'],
+    handL: ['LeftHand', 'HandLeft'],
+    handR: ['RightHand', 'HandRight'],
+    legL: ['LeftLeg', 'LegLeft', 'LeftShin'],
+    legR: ['RightLeg', 'LegRight', 'RightShin'],
+};
+/** 归一化骨骼名:去 mixamorig 前缀/冒号、去下划线、转小写。
+ *  "mixamorig:Head" / "Mixamorig_Head" / "Head" → "head" */
+export function normalizeBoneName(name) {
+    return name
+        .replace(/^mixamorig:?/i, '')
+        .replace(/_/g, '')
+        .toLowerCase();
+}
+/** 在骨架树里按部位找骨骼;找不到的部位缺省(Y Bot 实测
+ * 骨架前缀是 mixamorig、无冒号,归一化后天然兼容) */
+export function resolveAnchorBones(root) {
+    const bones = [];
+    root.traverse((o) => {
+        if (o.isBone)
+            bones.push(o);
+    });
+    const byNormalized = new Map();
+    for (const bone of bones) {
+        const key = normalizeBoneName(bone.name);
+        if (!byNormalized.has(key))
+            byNormalized.set(key, bone);
+    }
+    const found = {};
+    for (const part of BONE_PARTS) {
+        for (const candidate of BONE_CANDIDATES[part]) {
+            const bone = byNormalized.get(normalizeBoneName(candidate));
+            if (bone) {
+                found[part] = bone;
+                break;
+            }
+        }
+    }
+    return found;
+}
+export function makeBoneAnchorId(placementKey, part) {
+    return `bone:${placementKey}#${part}`;
+}
+export function parseBoneAnchorId(id) {
+    if (!id.startsWith('bone:'))
+        return null;
+    const hash = id.indexOf('#');
+    if (hash < 0)
+        return null;
+    const placementKey = id.slice(5, hash);
+    const part = id.slice(hash + 1);
+    if (!placementKey || !BONE_PARTS.includes(part))
+        return null;
+    return { placementKey, part };
+}
+/** anchorId(bone:…#part)→ 骨骼下的锚点节点 */
+const boneAnchors = new Map();
+/** 已登记的 placementKey → 当时的骨架根:同根重复登记直接短路——
+ * 放置注册表增删任一模型都会让所有 PlacedModelCore 的登记 effect
+ * 重跑,不守卫会把骨骼上的锚点节点摘掉重建,而已绑定到骨骼锚点上的
+ * 锚点网格(其子节点)随之脱离场景树,再没有任何路径把它挂回来 */
+const registeredRoots = new Map();
+/**
+ * 在放置实例上登记骨骼锚点:解析部位 → 挂节点 → 入表。
+ * 同 placementKey 重复调用先清旧组(热更新/重挂载防堆积);
+ * 同根重复调用(注册表增删导致的 effect 重跑)保持节点身份不重建。
+ * 无骨骼的模型自然解析为空,不进表。
+ */
+export function registerBoneAnchors(placementKey, root) {
+    if (registeredRoots.get(placementKey) === root)
+        return;
+    unregisterBoneAnchors(placementKey);
+    const found = resolveAnchorBones(root);
+    for (const part of BONE_PARTS) {
+        const bone = found[part];
+        if (!bone)
+            continue;
+        const anchor = new Object3DImpl();
+        anchor.name = `Anchor_${part}`;
+        bone.add(anchor);
+        boneAnchors.set(makeBoneAnchorId(placementKey, part), anchor);
+    }
+    registeredRoots.set(placementKey, root);
+}
+export function unregisterBoneAnchors(placementKey) {
+    for (const part of BONE_PARTS) {
+        const id = makeBoneAnchorId(placementKey, part);
+        const anchor = boneAnchors.get(id);
+        if (anchor) {
+            anchor.parent?.remove(anchor);
+            boneAnchors.delete(id);
+        }
+    }
+    registeredRoots.delete(placementKey);
+}
+export function getBoneAnchorObjects() {
+    return boneAnchors;
+}

package/dist/boneAnchors.test.d.ts

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

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

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

package/dist/boneAnchors.test.js

@@ -0,0 +1,98 @@
+// packages/camera-studio/src/boneAnchors.test.ts
+import { Bone, Object3D } from 'three';
+import { BONE_PARTS, parseBoneAnchorId, resolveAnchorBones, makeBoneAnchorId, registerBoneAnchors, unregisterBoneAnchors, getBoneAnchorObjects, } from './boneAnchors';
+function mixamoRig() {
+    // Y Bot 实测骨架的精简版:mixamorig 前缀、无冒号
+    const names = [
+        'mixamorigHips',
+        'mixamorigSpine',
+        'mixamorigSpine1',
+        'mixamorigSpine2',
+        'mixamorigNeck',
+        'mixamorigHead',
+        'mixamorigLeftHand',
+        'mixamorigRightHand',
+        'mixamorigLeftLeg',
+        'mixamorigRightLeg',
+    ];
+    const root = new Object3D();
+    const byName = new Map();
+    for (const name of names) {
+        const bone = new Bone();
+        bone.name = name;
+        byName.set(name, bone);
+    }
+    // brief 原稿只 root.add(hips)、其余骨骼游离在树外,traverse 不可达;
+    // 按"精简版实测骨架"的意图把全部骨骼挂进树(其余断言逐字不变)
+    for (const bone of byName.values())
+        root.add(bone);
+    return root;
+}
+describe('resolveAnchorBones', () => {
+    test('mixamo 骨架六个部位全命中', () => {
+        const found = resolveAnchorBones(mixamoRig());
+        expect(Object.keys(found).sort()).toEqual([...BONE_PARTS].sort());
+        expect(found.head?.name).toBe('mixamorigHead');
+        expect(found.chest?.name).toBe('mixamorigSpine1');
+        expect(found.handL?.name).toBe('mixamorigLeftHand');
+        expect(found.handR?.name).toBe('mixamorigRightHand');
+        expect(found.legL?.name).toBe('mixamorigLeftLeg');
+        expect(found.legR?.name).toBe('mixamorigRightLeg');
+    });
+    test('容忍冒号/大小写变体(mixamorig:Head / MixamorigHead)', () => {
+        const root = new Object3D();
+        for (const name of [
+            'mixamorig:Head',
+            'MixamorigSpine1',
+            'LEFTHAND',
+            'right_hand',
+        ]) {
+            const b = new Bone();
+            b.name = name;
+            root.add(b);
+        }
+        const found = resolveAnchorBones(root);
+        expect(found.head).toBeDefined();
+        expect(found.chest).toBeDefined();
+        expect(found.handL).toBeDefined();
+        expect(found.handR).toBeDefined();
+    });
+    test('无骨骼的静态模型全部落空', () => {
+        const root = new Object3D();
+        root.add(new Object3D());
+        expect(resolveAnchorBones(root)).toEqual({});
+    });
+});
+describe('bone anchor id', () => {
+    test('构造/解析互逆;坏 id 返回 null', () => {
+        const id = makeBoneAnchorId('Models / Y Bot', 'head');
+        expect(id).toBe('bone:Models / Y Bot#head');
+        expect(parseBoneAnchorId(id)).toEqual({
+            placementKey: 'Models / Y Bot',
+            part: 'head',
+        });
+        expect(parseBoneAnchorId('anchor:Anchor 1')).toBeNull();
+        expect(parseBoneAnchorId('bone:no-part-here')).toBeNull();
+        expect(parseBoneAnchorId('bone:k#nope')).toBeNull();
+    });
+});
+describe('registerBoneAnchors / unregisterBoneAnchors', () => {
+    test('登记后在 getBoneAnchorObjects 可查,按 placementKey 成组清理', () => {
+        const rig = mixamoRig();
+        registerBoneAnchors('Models / Y Bot', rig);
+        const all = getBoneAnchorObjects();
+        expect(all.size).toBe(6);
+        const headId = makeBoneAnchorId('Models / Y Bot', 'head');
+        // 锚点是挂到骨骼下的子节点
+        expect(all.get(headId)?.parent?.name).toBe('mixamorigHead');
+        unregisterBoneAnchors('Models / Y Bot');
+        expect(getBoneAnchorObjects().size).toBe(0);
+    });
+    test('同一模型重复登记不堆积(先清同组再挂)', () => {
+        const rig = mixamoRig();
+        registerBoneAnchors('M1', rig);
+        registerBoneAnchors('M1', rig);
+        expect(getBoneAnchorObjects().size).toBe(6);
+        unregisterBoneAnchors('M1');
+    });
+});