@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/anchorParenting.test.js

@@ -0,0 +1,87 @@
+// packages/camera-studio/src/anchorParenting.test.ts
+import { Euler, Object3D, Vector3 } from 'three';
+import { isDescendantAnchor, localOffsetForParent, needsParentEstablish, shouldClearMissingParent, detachAnchorMesh, } from './aimTargets';
+describe('isDescendantAnchor', () => {
+    // 父链:A ← B ← C(C 挂 B,B 挂 A);即 B、C 都是 A 的后代,C 是 B 的后代
+    const parentOf = (k) => ({ C: 'anchor:B', B: 'anchor:A', A: '' })[k] ?? '';
+    test('后代判 true;自己/祖先/旁系 false', () => {
+        expect(isDescendantAnchor('A', 'B', parentOf)).toBe(true);
+        expect(isDescendantAnchor('A', 'C', parentOf)).toBe(true);
+        expect(isDescendantAnchor('B', 'C', parentOf)).toBe(true);
+        expect(isDescendantAnchor('C', 'B', parentOf)).toBe(false); // B 是 C 的祖先
+        expect(isDescendantAnchor('C', 'A', parentOf)).toBe(false);
+        expect(isDescendantAnchor('C', 'C', parentOf)).toBe(false); // 自己
+    });
+});
+describe('localOffsetForParent', () => {
+    test('父级世界矩阵逆 × 子世界坐标 = 局部偏移', () => {
+        const parent = new Object3D();
+        parent.position.set(10, 0, 0);
+        parent.updateMatrixWorld(true);
+        const childWorld = new Vector3(12, 3, -1);
+        const out = new Vector3();
+        localOffsetForParent(childWorld, parent, out);
+        expect(out.x).toBeCloseTo(2);
+        expect(out.y).toBeCloseTo(3);
+        expect(out.z).toBeCloseTo(-1);
+    });
+    test('父级带旋转也算得对', () => {
+        const parent = new Object3D();
+        parent.position.set(0, 5, 0);
+        parent.quaternion.setFromEuler(new Euler(0, Math.PI / 2, 0));
+        parent.updateMatrixWorld(true);
+        // 子在世界 (1,5,0):父级绕 Y 转 90°(+X 旋向 -Z),局部 = R⁻¹ × (世界 - 父位置)
+        // 手算:R(90°) 把 +X 转到 -Z,故 R⁻¹(1,0,0) = (0,0,1)
+        const out = new Vector3();
+        localOffsetForParent(new Vector3(1, 5, 0), parent, out);
+        expect(out.x).toBeCloseTo(0);
+        expect(out.y).toBeCloseTo(0);
+        expect(out.z).toBeCloseTo(1);
+    });
+});
+describe('Critical-1 回归:恢复未建立的绑定不被看护清除,由重试补建', () => {
+    // 时序(刷新页面,parent 持久绑定到放置模型):第 1 次提交 parentId
+    // 是 fallback '',第 2 次提交变回持久值 'model:X',此时模型还在
+    // Suspense 加载、lookup 解析不到。旧实现里看护 effect 会把这个
+    // 空窗当"父级消失"清掉持久绑定;新实现按下面的切分判定:
+    // 看护不清除(从未绑定成功),useFrame 重试循环负责建立,建立后
+    // 解析不到才允许清除(真删场景)。
+    test('未绑定成功过的父级:看护永不清除;重试在绑定成功后停;真删才清除', () => {
+        const parentId = 'model:X';
+        // 本会话绑定记录:刷新后为空
+        let bound = null;
+        // 加载空窗:解析不到,但绑定从未建立 → 看护不清除(Critical-1 核心断言)
+        expect(shouldClearMissingParent(bound, parentId, false)).toBe(false);
+        // 重试循环:需要建立
+        expect(needsParentEstablish(bound, parentId)).toBe(true);
+        // 模型加载完,重试建立成功(只挂不换算,position 属性保持持久局部偏移)
+        bound = parentId;
+        expect(needsParentEstablish(bound, parentId)).toBe(false);
+        // 建立之后父级真被删(解析不到)→ 看护清除+定格(真删场景行为不变)
+        expect(shouldClearMissingParent(bound, parentId, false)).toBe(true);
+        // 解析得到 → 不清除
+        expect(shouldClearMissingParent(bound, parentId, true)).toBe(false);
+    });
+    test('闸按 parentId 精确匹配:绑定 A 时 parentId 是 B → 不清除', () => {
+        expect(shouldClearMissingParent('anchor:A', 'anchor:B', false)).toBe(false);
+        expect(needsParentEstablish('anchor:A', 'anchor:B')).toBe(true);
+    });
+    test('无父级:看护与重试都不动作', () => {
+        expect(shouldClearMissingParent('model:X', '', false)).toBe(false);
+        expect(needsParentEstablish('model:X', '')).toBe(false);
+    });
+});
+describe('detachAnchorMesh(终审复审:删锚清幽灵网格)', () => {
+    test('绑在伪造骨骼上的锚点网格被移除,骨骼子树无残留', () => {
+        const bone = new Object3D();
+        const mesh = new Object3D();
+        bone.add(mesh);
+        expect(bone.children).toContain(mesh);
+        detachAnchorMesh(mesh);
+        expect(mesh.parent).toBeNull();
+        expect(bone.children).toHaveLength(0);
+    });
+    test('null(卸载时 ref 已置空的等价输入)静默 no-op', () => {
+        expect(() => detachAnchorMesh(null)).not.toThrow();
+    });
+});

package/dist/anchorsRegistry.d.ts

@@ -0,0 +1,45 @@
+import type { ISheet, ISheetObject } from '@dreamerbird/core';
+export declare const ANCHORS_REGISTRY_KEY = "Anchors";
+export type AnchorSeed = {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+export declare function getAnchorsRegistry(sheet: ISheet): ISheetObject<any>;
+export declare function parseAnchorKeys(json: string): string[];
+export declare function readAnchorKeys(registry: ISheetObject<any>): string[];
+export declare function nextAnchorKey(existing: readonly string[]): string;
+export declare function useAnchorsList(sheet: ISheet): string[];
+export declare function stashAnchorSeed(key: string, seed: AnchorSeed): void;
+export declare function consumeAnchorSeed(key: string): AnchorSeed | undefined;
+/** 添加锚点:注册表加一行(App 按清单渲染,组件挂载即创建对象) */
+export declare function addAnchorToRegistry(sheet: ISheet, key: string, seed?: AnchorSeed): void;
+/**
+ * 删除锚点时一并回退的子级锚点(parent 指向被删锚点);
+ * 由调用方经 aimTargets.collectAnchorChildResets 收集
+ * (同 removePathFromRegistry 的 boundCameras 模式:收集需要运行时
+ * 登记表,本模块不反向依赖 aimTargets)。
+ */
+export type AnchorChildReset = {
+    obj: ISheetObject<any>;
+    /** 子锚点的世界坐标定格(解绑后 position 语义回到世界坐标,画面不跳) */
+    freeze: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+/**
+ * 删除锚点:单个事务完成 forgetObject + 子级解绑/定格 + 注册表移除 =
+ * 一步撤销(2026-10-19,Task 14 合并;原先两个事务两步撤销)。
+ *
+ * forgetObject 走 stateEditors 按地址清持久数据,不要求挂载中的对象
+ * 句柄(schema 编辑器对无持久数据的对象先查后删,幂等不抛)。
+ * children 必须折进同一事务:不折的话子组件的「父级消失看护」会在
+ * 删除后补一笔提交,撤销删除时先看护提交把撤销游标顶掉
+ * (同 removePathFromRegistry 注释的撤销陷阱)。
+ */
+export declare function removeAnchor(sheet: ISheet, key: string, children?: AnchorChildReset[]): void;
+//# sourceMappingURL=anchorsRegistry.d.ts.map

package/dist/anchorsRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchorsRegistry.d.ts","sourceRoot":"","sources":["../src/anchorsRegistry.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAC,MAAM,EAAE,YAAY,EAAC,MAAM,mBAAmB,CAAA;AAO3D,eAAO,MAAM,oBAAoB,YAAY,CAAA;AAE7C,MAAM,MAAM,UAAU,GAAG;IAAC,QAAQ,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAAA;CAAC,CAAA;AAEtE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAMnE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAUtD;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE,CAEpE;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMjE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAQtD;AAID,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,QAE5D;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAIrE;AAED,uCAAuC;AACvC,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,UAAU,GAChB,IAAI,CAYN;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,CAAA;IACtB,6CAA6C;IAC7C,MAAM,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,gBAAgB,EAAO,GAChC,IAAI,CAmBN"}

package/dist/anchorsRegistry.js

@@ -0,0 +1,101 @@
+/**
+ * 独立锚点注册表:场景里有几个空物体锚点 = 清单里有几行。
+ * 模式照搬 cameraRegistry(隐藏注册表对象存 key 数组 JSON;
+ * 增删都是可撤销事务;种子暂存-挂载消费)。锚点与相机平级独立,
+ * 可被相机瞄准、可绑定父级。
+ */
+import { getStudioSync, types as t, val } from '@dreamerbird/core';
+// 内部 Studio 通道:合并事务需要 stateEditors.forgetObject(按地址清持久
+// 数据,不要求对象已挂载)——与 keyframeTracks/poseTrack 同先例
+import getStudio from '@dreamerbird/studio/getStudio';
+import { useEffect, useMemo, useState } from 'react';
+export const ANCHORS_REGISTRY_KEY = 'Anchors';
+export function getAnchorsRegistry(sheet) {
+    return sheet.object(ANCHORS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+}
+export function parseAnchorKeys(json) {
+    try {
+        const list = JSON.parse(json);
+        if (!Array.isArray(list))
+            return [];
+        return list.filter((k) => typeof k === 'string' && k.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+export function readAnchorKeys(registry) {
+    return parseAnchorKeys(val(registry.props.list));
+}
+export function nextAnchorKey(existing) {
+    const used = new Set(existing);
+    for (let n = 1;; n++) {
+        const key = `Anchor ${n}`;
+        if (!used.has(key))
+            return key;
+    }
+}
+export function useAnchorsList(sheet) {
+    const registry = useMemo(() => getAnchorsRegistry(sheet), [sheet]);
+    const [list, setList] = useState(() => readAnchorKeys(registry));
+    useEffect(() => {
+        setList(readAnchorKeys(registry));
+        return registry.onValuesChange(() => setList(readAnchorKeys(registry)));
+    }, [registry]);
+    return list;
+}
+const pendingSeeds = new Map();
+export function stashAnchorSeed(key, seed) {
+    pendingSeeds.set(key, seed);
+}
+export function consumeAnchorSeed(key) {
+    const seed = pendingSeeds.get(key);
+    pendingSeeds.delete(key);
+    return seed;
+}
+/** 添加锚点:注册表加一行(App 按清单渲染,组件挂载即创建对象) */
+export function addAnchorToRegistry(sheet, key, seed) {
+    const studio = getStudioSync();
+    if (!studio)
+        return;
+    const registry = getAnchorsRegistry(sheet);
+    const list = readAnchorKeys(registry);
+    if (list.includes(key))
+        return;
+    const scrub = studio.scrub();
+    scrub.capture(({ set }) => set(registry.props.list, JSON.stringify([...list, key])));
+    scrub.commit();
+    if (seed)
+        stashAnchorSeed(key, seed);
+}
+/**
+ * 删除锚点:单个事务完成 forgetObject + 子级解绑/定格 + 注册表移除 =
+ * 一步撤销(2026-10-19,Task 14 合并;原先两个事务两步撤销)。
+ *
+ * forgetObject 走 stateEditors 按地址清持久数据,不要求挂载中的对象
+ * 句柄(schema 编辑器对无持久数据的对象先查后删,幂等不抛)。
+ * children 必须折进同一事务:不折的话子组件的「父级消失看护」会在
+ * 删除后补一笔提交,撤销删除时先看护提交把撤销游标顶掉
+ * (同 removePathFromRegistry 注释的撤销陷阱)。
+ */
+export function removeAnchor(sheet, key, children = []) {
+    const studio = getStudio();
+    if (!studio)
+        return;
+    pendingSeeds.delete(key);
+    const registry = getAnchorsRegistry(sheet);
+    const list = readAnchorKeys(registry);
+    studio.transaction(({ set, stateEditors }) => {
+        stateEditors.coreByProject.historic.sheetsById.forgetObject({
+            projectId: sheet.address.projectId,
+            sheetId: sheet.address.sheetId,
+            // 业务 key 跨适配层按不透明字符串传递,此处回到 core 的名义类型
+            objectKey: key,
+        });
+        for (const { obj, freeze } of children) {
+            set(obj.props.parent, '');
+            set(obj.props.position, { x: freeze.x, y: freeze.y, z: freeze.z });
+        }
+        set(registry.props.list, JSON.stringify(list.filter((k) => k !== key)));
+    });
+}

package/dist/anchorsRegistry.test.d.ts

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

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

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

package/dist/anchorsRegistry.test.js

@@ -0,0 +1,29 @@
+// packages/camera-studio/src/anchorsRegistry.test.ts
+import { parseAnchorKeys, nextAnchorKey, stashAnchorSeed, consumeAnchorSeed, } from './anchorsRegistry';
+describe('parseAnchorKeys', () => {
+    test('合法清单;坏 JSON/非数组/非字符串项回退', () => {
+        expect(parseAnchorKeys('["Anchor 1","Anchor 2"]')).toEqual([
+            'Anchor 1',
+            'Anchor 2',
+        ]);
+        expect(parseAnchorKeys('not json')).toEqual([]);
+        expect(parseAnchorKeys('{"a":1}')).toEqual([]);
+        expect(parseAnchorKeys('[1,"Anchor 1",null]')).toEqual(['Anchor 1']);
+    });
+});
+describe('nextAnchorKey', () => {
+    test('空清单给 Anchor 1;占用后取第一个空位', () => {
+        expect(nextAnchorKey([])).toBe('Anchor 1');
+        expect(nextAnchorKey(['Anchor 1', 'Anchor 2'])).toBe('Anchor 3');
+        expect(nextAnchorKey(['Anchor 1', 'Anchor 3'])).toBe('Anchor 2');
+    });
+});
+describe('anchor seed', () => {
+    test('存取一次即清;未存的 key 返回 undefined', () => {
+        stashAnchorSeed('Anchor 1', { position: { x: 1, y: 2, z: 3 } });
+        expect(consumeAnchorSeed('Anchor 1')).toEqual({
+            position: { x: 1, y: 2, z: 3 },
+        });
+        expect(consumeAnchorSeed('Anchor 1')).toBeUndefined();
+    });
+});

package/dist/assetLibrary/AssetLibraryPanel.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 资产库框体:模型/路径/姿势/动作四种类型的选择面板,一个组件四个实例。
+ *
+ * 样式对齐 theatre 原生面板:骨架/标题栏配色取自 studio BasePanel
+ * (panel-bg #282b2f、TitleBar #25272b),按钮复用 studio DetailPanelButton,
+ * 卡片右键菜单复用 studio ContextMenu。--theatre-* 令牌定义在 studio 的
+ * shadow DOM(:host),主文档不可见,一律带同值兜底——令牌将来全局化时
+ * 自动接管(同 TopToolbar 的策略)。
+ */
+import React from 'react';
+import type { PathPreset } from '../pathPresets';
+import type { AnimationEntry, ModelEntry, PoseEntry } from './types';
+export type AssetKind = 'model' | 'pose' | 'animation' | 'path';
+export declare function AssetLibraryPanel({ kind, onPlaceModel, onDragStartModel, onPlacePreset, onDragStartPreset, filterRig, onClose, onApplyAnimation, onApplyPose, onSavePose, canSavePose, applyDisabled, disabled, poseStatus, poseKeyframeCount, onWritePoseKeyframe, onClearPose, }: {
+    kind: AssetKind;
+    onPlaceModel?: (entry: ModelEntry) => void;
+    onDragStartModel?: (entry: ModelEntry) => void;
+    onPlacePreset?: (preset: PathPreset) => void;
+    onDragStartPreset?: (preset: PathPreset) => void;
+    filterRig?: string;
+    onClose: () => void;
+    onApplyAnimation?: (entry: AnimationEntry) => void;
+    onApplyPose?: (entry: PoseEntry) => void;
+    onSavePose?: () => void;
+    canSavePose?: boolean;
+    applyDisabled?: boolean;
+    disabled?: boolean;
+    /** 姿势状态行(spec §6.2):来源文案,由 App 用 poseStatusText 算好传入 */
+    poseStatus?: string;
+    /** 姿势轨道关键帧数(命令式读取,随 App 重渲刷新) */
+    poseKeyframeCount?: number;
+    onWritePoseKeyframe?: () => void;
+    onClearPose?: () => void;
+}): React.JSX.Element;
+//# sourceMappingURL=AssetLibraryPanel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AssetLibraryPanel.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/AssetLibraryPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAiD,MAAM,OAAO,CAAA;AAOrE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,gBAAgB,CAAA;AAO9C,OAAO,KAAK,EAAC,cAAc,EAAE,UAAU,EAAE,SAAS,EAAC,MAAM,SAAS,CAAA;AAGlE,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAA;AAkW/D,wBAAgB,iBAAiB,CAAC,EAChC,IAAI,EACJ,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,SAAS,EACT,OAAO,EACP,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,WAAW,EACX,aAAa,EACb,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EACnB,WAAW,GACZ,EAAE;IACD,IAAI,EAAE,SAAS,CAAA;IACf,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;IAC1C,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;IAC9C,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;IAC5C,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;IAChD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IAClD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAA;IACxC,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IACvB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iCAAiC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAA;IAChC,WAAW,CAAC,EAAE,MAAM,IAAI,CAAA;CACzB,qBA4ZA"}