@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/aimTargets.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 瞄准/父级绑定的目标 id 方案与解析。
+ * id 取值:''(无)| anchor:<key>(独立锚点)| bone:<placement>#<part>(骨骼锚点)
+ *        | model:<placementKey>(整个放置模型)| camera:<cameraKey>(拍摄相机)。
+ * 解析分两层:纯函数 resolveTargetObject(id, lookup) 供测试注入;
+ * resolveAimTarget / resolveAnchorParent 读运行时登记表,供帧驱动调用。
+ */
+import { Vector3 } from 'three';
+import type { Object3D } from 'three';
+import type { BonePart } from './boneAnchors';
+import type { ISheet } from '@dreamerbird/core';
+import type { AnchorChildReset } from './anchorsRegistry';
+export type TargetKind = 'anchor' | 'bone' | 'model' | 'camera';
+export declare function parseTargetId(id: string): {
+    kind: 'anchor';
+    key: string;
+} | {
+    kind: 'bone';
+    placementKey: string;
+    part: BonePart;
+} | {
+    kind: 'model';
+    key: string;
+} | {
+    kind: 'camera';
+    key: string;
+} | null;
+export declare function makeTargetId(kind: TargetKind, key: string, part?: BonePart): string;
+/**
+ * 只探测不创建:sheet.object 会把不存在的对象顺手建出来。顶层扁平化
+ * (相机/模型不再套文件夹)后取名要与全场景对象防撞,靠它先问路径占用。
+ * 探测不到/注册表未建一律 false(对齐 aimTargetOptions 的 privateAPI 用法)
+ */
+export declare function sheetObjectExists(sheet: ISheet, key: string): boolean;
+export interface TargetLookup {
+    anchors: ReadonlyMap<string, Object3D>;
+    bones: ReadonlyMap<string, Object3D>;
+    models: ReadonlyMap<string, Object3D>;
+    cameras: ReadonlyMap<string, Object3D>;
+}
+export declare function resolveTargetObject(id: string, lookup: TargetLookup): Object3D | null;
+/** 订阅登记表变更,返回退订函数 */
+export declare function subscribeTargetRegistry(fn: () => void): () => void;
+/** 登记表变更广播;各 register/unregister 路径在写表后调用 */
+export declare function notifyTargetRegistryChange(): void;
+export declare function registerAnchorObject(key: string, obj: Object3D | null): void;
+export declare function getAnchorObjects(): ReadonlyMap<string, Object3D>;
+/** Anchors 组件挂载时登记 home group;卸载清 null */
+export declare function registerAnchorHome(obj: Object3D | null): void;
+export declare function defaultTargetLookup(): TargetLookup;
+export declare function resolveAimTarget(id: string): Object3D | null;
+export declare function resolveAnchorParent(id: string): Object3D | null;
+export declare function setAimOptionsSheet(sheet: ISheet | null): void;
+export declare function aimTargetOptions(): {
+    [key: string]: string;
+};
+/**
+ * 「父级」下拉选项(锚点面板,按锚点 key 排除自己与后代防环)。
+ * 候选:其他锚点 + 拍摄相机 + 放置模型 + 骨骼锚点。
+ */
+export declare function anchorParentOptionsFor(selfKey: string): {
+    [key: string]: string;
+};
+/** 环检测:candidate 沿父链向上能否到达 selfKey(candidate 是 self 的后代) */
+export declare function isDescendantAnchor(selfKey: string, candidateKey: string, parentOf: (key: string) => string): boolean;
+/** 世界坐标 → 父级局部偏移(纯函数,绑定/解绑定格用) */
+export declare function localOffsetForParent(childWorld: Vector3, parentObj: Object3D, out: Vector3): Vector3;
+/**
+ * 命令侧父级切换的定格计划(2026-10-19,Agent API F1 修复):
+ * anchors.setParent/clearParent 把坐标定格折进写 parent 的同一事务,
+ * 否则 AnchorObject 的看护 effect 会在属性变化后再补一笔定格提交——
+ * 两步撤销,undo 一次只回属性不回定格,锚点跳变(撤销陷阱,同
+ * removeAnchor/removePathFromRegistry 注释)。
+ *
+ * 同步读当前世界坐标,算出换父后 position 属性应取值(绑定=新父局部
+ * 偏移;解绑=世界坐标)。返回的 reparent 必须在事务提交后、同一调用栈
+ * 内执行:抢在包装器应用新 position 与看护 effect 之前完成换父,包装器
+ * 应用落在新父之下、世界坐标不变,看护的同值守卫看到 persisted==定格值
+ * 即跳过提交(只推进游标)。
+ *
+ * 返回 null = 锚点网格未登记(未挂载)或父级目标运行时对象未就绪
+ * (异步加载中)——调用方按 INVALID_STATE 拒绝(可重试),不写半悬挂
+ * 状态。
+ */
+export declare function planAnchorParentFreeze(key: string, parentId: string): {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    reparent: () => void;
+} | null;
+/**
+ * 锚点卸载时脱离命令式父级(骨骼/模型上的锚点被删的清理)。
+ * fiber v9 卸载按 JSX 父实例 remove,对换父后的网格是 no-op,不脱离会
+ * 残留在场景里,可见不可选,绑骨骼上还会跟随动画。
+ * 注意:passive useEffect cleanup 执行时 React 已把 ref 置 null
+ * (实测 React 19.2.8,layout cleanup 才保有),调用方必须在 effect
+ * 体内捕获 mesh 传进来。
+ */
+export declare function detachAnchorMesh(mesh: Object3D | null): void;
+/**
+ * 绑定重试循环的判定:有父级目标、且本会话尚未对当前 parentId 绑定
+ * 成功。刷新/撤销恢复的持久绑定在异步目标(放置模型/骨骼锚点,
+ * Suspense 加载完才注册)就绪前一直满足本条件,由 useFrame 每帧补建;
+ * 建立成功后写入 boundParentId,不再重试。
+ */
+export declare function needsParentEstablish(boundParentId: string | null, parentId: string): boolean;
+/**
+ * 父级消失看护的清除判定:本会话曾对当前 parentId 绑定成功、且此刻
+ * 解析不到 → 允许「清除 parent + 定格世界坐标」。从未绑定成功过的
+ * 父级(刷新恢复/加载中)判 false:不清不定格,交给重试循环直到建立
+ * ——否则异步目标加载完成前的空窗会被误当「父级消失」,持久绑定被清掉。
+ */
+export declare function shouldClearMissingParent(boundParentId: string | null, parentId: string, resolvable: boolean): boolean;
+/**
+ * 删除锚点前收集以它为父级的子锚点(连同世界定格),交给
+ * anchorsRegistry.removeAnchor 折进删除的同一事务(同
+ * collectBoundCameraResets 对路径删除的作用;撤销陷阱见
+ * pathRegistry.removePathFromRegistry 注释)。
+ *
+ * 只探测不创建:子锚点对象经内部对象表 peek(getObject 不创建),
+ * 世界定格读运行时登记表(anchorObjects)的节点。节点缺失(未挂载)
+ * 的子锚点跳过——局部偏移没有世界定格可写,持久绑定留给挂载后的
+ * 重试/看护处理。
+ */
+export declare function collectAnchorChildResets(sheet: ISheet, parentKey: string): AnchorChildReset[];
+//# sourceMappingURL=aimTargets.d.ts.map

package/dist/aimTargets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aimTargets.d.ts","sourceRoot":"","sources":["../src/aimTargets.ts"],"names":[],"mappings":"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"}

package/dist/aimTargets.js

@@ -0,0 +1,367 @@
+// packages/camera-studio/src/aimTargets.ts
+/**
+ * 瞄准/父级绑定的目标 id 方案与解析。
+ * id 取值:''(无)| anchor:<key>(独立锚点)| bone:<placement>#<part>(骨骼锚点)
+ *        | model:<placementKey>(整个放置模型)| camera:<cameraKey>(拍摄相机)。
+ * 解析分两层:纯函数 resolveTargetObject(id, lookup) 供测试注入;
+ * resolveAimTarget / resolveAnchorParent 读运行时登记表,供帧驱动调用。
+ */
+import { Matrix4, Vector3 } from 'three';
+import { translate } from '@dreamerbird/studio/i18n';
+import { val } from '@dreamerbird/core';
+import { privateAPI } from '@dreamerbird/core/privateAPIs';
+import { getBoneAnchorObjects, makeBoneAnchorId, parseBoneAnchorId, } from './boneAnchors';
+import { getPlacedInstances, readPlacementEntries } from './PlacementManager';
+import { cameraDisplayName, getCamerasRegistry, getShotCameraObjects, readCameraEntries, } from './cameraRegistry';
+import { getAnchorsRegistry, readAnchorKeys } from './anchorsRegistry';
+const KIND_PREFIXES = ['anchor', 'bone', 'model', 'camera'];
+export function parseTargetId(id) {
+    if (id === '')
+        return null;
+    const bone = parseBoneAnchorId(id);
+    if (bone)
+        return { kind: 'bone', ...bone };
+    const colon = id.indexOf(':');
+    if (colon <= 0)
+        return null;
+    const kind = id.slice(0, colon);
+    const key = id.slice(colon + 1);
+    if (!KIND_PREFIXES.includes(kind) || !key)
+        return null;
+    if (kind === 'bone')
+        return null; // 已被 parseBoneAnchorId 拦截,带 # 校验
+    return { kind, key };
+}
+export function makeTargetId(kind, key, part) {
+    if (kind === 'bone')
+        return makeBoneAnchorId(key, part);
+    return `${kind}:${key}`;
+}
+/**
+ * 只探测不创建:sheet.object 会把不存在的对象顺手建出来。顶层扁平化
+ * (相机/模型不再套文件夹)后取名要与全场景对象防撞,靠它先问路径占用。
+ * 探测不到/注册表未建一律 false(对齐 aimTargetOptions 的 privateAPI 用法)
+ */
+export function sheetObjectExists(sheet, key) {
+    try {
+        return Boolean(privateAPI(sheet).getObject(key));
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveTargetObject(id, lookup) {
+    const parsed = parseTargetId(id);
+    if (!parsed)
+        return null;
+    switch (parsed.kind) {
+        case 'anchor':
+            return lookup.anchors.get(parsed.key) ?? null;
+        case 'bone':
+            return (lookup.bones.get(makeBoneAnchorId(parsed.placementKey, parsed.part)) ??
+                null);
+        case 'model':
+            return lookup.models.get(parsed.key) ?? null;
+        case 'camera':
+            return lookup.cameras.get(parsed.key) ?? null;
+    }
+}
+/** 独立锚点的 theatreKey → 场景网格(Anchors 组件登记) */
+const anchorObjects = new Map();
+/**
+ * 运行时目标登记表(锚点/相机,bones/placedInstances 在 Task 8 接线)
+ * 的变更订阅:挂载登记/卸载注销时广播。ShotCamera 订阅后重渲染,
+ * 持久态 aimTarget 指向的目标在目标挂载登记瞬间 tracking 立即翻正,
+ * 不等到无关重渲染;目标被删同理即时回退自由朝向(规格§4)。
+ */
+const targetRegistryListeners = new Set();
+/** 订阅登记表变更,返回退订函数 */
+export function subscribeTargetRegistry(fn) {
+    targetRegistryListeners.add(fn);
+    return () => {
+        targetRegistryListeners.delete(fn);
+    };
+}
+/** 登记表变更广播;各 register/unregister 路径在写表后调用 */
+export function notifyTargetRegistryChange() {
+    for (const fn of targetRegistryListeners)
+        fn();
+}
+export function registerAnchorObject(key, obj) {
+    if (obj)
+        anchorObjects.set(key, obj);
+    else
+        anchorObjects.delete(key);
+    notifyTargetRegistryChange();
+}
+export function getAnchorObjects() {
+    return anchorObjects;
+}
+/**
+ * 锚点网格的「娘家」挂载点(Anchors 组件的 home group):解绑/父级消失
+ * 时挂回这里。命令侧(anchors.clearParent)同步换父也需要它,故随
+ * Anchors 挂载登记进模块级(单页单场景,同 anchorObjects)。
+ */
+let anchorHome = null;
+/** Anchors 组件挂载时登记 home group;卸载清 null */
+export function registerAnchorHome(obj) {
+    anchorHome = obj;
+}
+export function defaultTargetLookup() {
+    return {
+        anchors: anchorObjects,
+        bones: getBoneAnchorObjects(),
+        models: getPlacedInstances(),
+        cameras: getShotCameraObjects(),
+    };
+}
+export function resolveAimTarget(id) {
+    return resolveTargetObject(id, defaultTargetLookup());
+}
+export function resolveAnchorParent(id) {
+    return resolveTargetObject(id, defaultTargetLookup());
+}
+/**
+ * 「瞄准目标」下拉选项(模块级,studio 面板渲染时调用)。
+ * 「无」+ 独立锚点(经 optionsSheet 读 Anchors 注册表,Task 6 落地,
+ * 未落地前退化为空)+ 骨骼锚点(遍历运行时表,Task 8 接入数据)。
+ */
+let optionsSheet = null;
+export function setAimOptionsSheet(sheet) {
+    optionsSheet = sheet;
+}
+export function aimTargetOptions() {
+    const options = { '': translate('pg.props.aimNone') };
+    if (!optionsSheet)
+        return options;
+    try {
+        for (const key of readAnchorKeys(getAnchorsRegistry(optionsSheet))) {
+            options[makeTargetId('anchor', key)] = key;
+        }
+    }
+    catch {
+        // Anchors 注册表尚未创建:跳过
+    }
+    // 骨骼锚点按模型分组:bone:<placement>#part → "<模型显示名> · <部位名>"
+    const byPlacement = new Map();
+    for (const id of getBoneAnchorObjects().keys()) {
+        const parsed = parseBoneAnchorId(id);
+        if (!parsed)
+            continue;
+        const list = byPlacement.get(parsed.placementKey) ?? [];
+        list.push(parsed.part);
+        byPlacement.set(parsed.placementKey, list);
+    }
+    for (const [placementKey, parts] of byPlacement) {
+        const modelName = placementDisplayName(optionsSheet, placementKey);
+        for (const part of parts) {
+            options[makeTargetId('bone', placementKey, part)] =
+                `${modelName} · ${translate(`pg.parts.${part}`)}`;
+        }
+    }
+    return options;
+}
+/**
+ * 「父级」下拉选项(锚点面板,按锚点 key 排除自己与后代防环)。
+ * 候选:其他锚点 + 拍摄相机 + 放置模型 + 骨骼锚点。
+ */
+export function anchorParentOptionsFor(selfKey) {
+    const options = {
+        '': translate('pg.props.parentNone'),
+    };
+    if (!optionsSheet)
+        return options;
+    const sheet = optionsSheet;
+    const parentOf = (key) => {
+        try {
+            // 只探测不创建:sheet.object 会把不存在的对象顺手建出来
+            // (对齐 CameraPath.pathExists 的 privateAPI 用法)
+            const obj = privateAPI(sheet).getObject(key);
+            return obj ? val(obj.props.parent) ?? '' : '';
+        }
+        catch {
+            return '';
+        }
+    };
+    try {
+        for (const key of readAnchorKeys(getAnchorsRegistry(sheet))) {
+            if (key === selfKey)
+                continue;
+            if (isDescendantAnchor(selfKey, key, parentOf))
+                continue;
+            options[makeTargetId('anchor', key)] = key;
+        }
+    }
+    catch {
+        // 注册表未建
+    }
+    try {
+        for (const entry of readCameraEntries(getCamerasRegistry(sheet))) {
+            options[makeTargetId('camera', entry.cameraKey)] = cameraDisplayName(entry.cameraKey);
+        }
+    }
+    catch {
+        // 相机注册表未建
+    }
+    try {
+        for (const entry of readPlacementEntries(sheet)) {
+            options[makeTargetId('model', entry.key)] = entry.key.replace(/^Models \/ /, '');
+        }
+    }
+    catch {
+        // 放置注册表未建
+    }
+    // 骨骼锚点(分组同 aimTargetOptions)
+    const byPlacement = new Map();
+    for (const id of getBoneAnchorObjects().keys()) {
+        const parsed = parseBoneAnchorId(id);
+        if (!parsed)
+            continue;
+        const list = byPlacement.get(parsed.placementKey) ?? [];
+        list.push(parsed.part);
+        byPlacement.set(parsed.placementKey, list);
+    }
+    for (const [placementKey, parts] of byPlacement) {
+        const modelName = placementDisplayName(sheet, placementKey);
+        for (const part of parts) {
+            options[makeTargetId('bone', placementKey, part)] =
+                `${modelName} · ${translate(`pg.parts.${part}`)}`;
+        }
+    }
+    return options;
+}
+/** 环检测:candidate 沿父链向上能否到达 selfKey(candidate 是 self 的后代) */
+export function isDescendantAnchor(selfKey, candidateKey, parentOf) {
+    let cur = parentOf(candidateKey);
+    let guard = 0;
+    while (cur && guard++ < 100) {
+        if (cur === `anchor:${selfKey}`)
+            return true;
+        const parsed = parseTargetId(cur);
+        cur = parsed && parsed.kind === 'anchor' ? parentOf(parsed.key) : '';
+    }
+    return false;
+}
+/** 世界坐标 → 父级局部偏移(纯函数,绑定/解绑定格用) */
+export function localOffsetForParent(childWorld, parentObj, out) {
+    parentObj.updateWorldMatrix(true, false);
+    const inv = new Matrix4().copy(parentObj.matrixWorld).invert();
+    return out.copy(childWorld).applyMatrix4(inv);
+}
+/**
+ * 命令侧父级切换的定格计划(2026-10-19,Agent API F1 修复):
+ * anchors.setParent/clearParent 把坐标定格折进写 parent 的同一事务,
+ * 否则 AnchorObject 的看护 effect 会在属性变化后再补一笔定格提交——
+ * 两步撤销,undo 一次只回属性不回定格,锚点跳变(撤销陷阱,同
+ * removeAnchor/removePathFromRegistry 注释)。
+ *
+ * 同步读当前世界坐标,算出换父后 position 属性应取值(绑定=新父局部
+ * 偏移;解绑=世界坐标)。返回的 reparent 必须在事务提交后、同一调用栈
+ * 内执行:抢在包装器应用新 position 与看护 effect 之前完成换父,包装器
+ * 应用落在新父之下、世界坐标不变,看护的同值守卫看到 persisted==定格值
+ * 即跳过提交(只推进游标)。
+ *
+ * 返回 null = 锚点网格未登记(未挂载)或父级目标运行时对象未就绪
+ * (异步加载中)——调用方按 INVALID_STATE 拒绝(可重试),不写半悬挂
+ * 状态。
+ */
+export function planAnchorParentFreeze(key, parentId) {
+    const node = anchorObjects.get(key);
+    if (!node)
+        return null;
+    const world = node.getWorldPosition(new Vector3());
+    if (parentId === '') {
+        const home = anchorHome;
+        if (!home)
+            return null;
+        return {
+            position: { x: world.x, y: world.y, z: world.z },
+            reparent: () => {
+                home.add(node);
+            },
+        };
+    }
+    const parentObj = resolveAnchorParent(parentId);
+    if (!parentObj)
+        return null;
+    const local = localOffsetForParent(world, parentObj, new Vector3());
+    return {
+        position: { x: local.x, y: local.y, z: local.z },
+        reparent: () => {
+            parentObj.add(node);
+        },
+    };
+}
+/**
+ * 锚点卸载时脱离命令式父级(骨骼/模型上的锚点被删的清理)。
+ * fiber v9 卸载按 JSX 父实例 remove,对换父后的网格是 no-op,不脱离会
+ * 残留在场景里,可见不可选,绑骨骼上还会跟随动画。
+ * 注意:passive useEffect cleanup 执行时 React 已把 ref 置 null
+ * (实测 React 19.2.8,layout cleanup 才保有),调用方必须在 effect
+ * 体内捕获 mesh 传进来。
+ */
+export function detachAnchorMesh(mesh) {
+    mesh?.removeFromParent();
+}
+/**
+ * 绑定重试循环的判定:有父级目标、且本会话尚未对当前 parentId 绑定
+ * 成功。刷新/撤销恢复的持久绑定在异步目标(放置模型/骨骼锚点,
+ * Suspense 加载完才注册)就绪前一直满足本条件,由 useFrame 每帧补建;
+ * 建立成功后写入 boundParentId,不再重试。
+ */
+export function needsParentEstablish(boundParentId, parentId) {
+    return parentId !== '' && boundParentId !== parentId;
+}
+/**
+ * 父级消失看护的清除判定:本会话曾对当前 parentId 绑定成功、且此刻
+ * 解析不到 → 允许「清除 parent + 定格世界坐标」。从未绑定成功过的
+ * 父级(刷新恢复/加载中)判 false:不清不定格,交给重试循环直到建立
+ * ——否则异步目标加载完成前的空窗会被误当「父级消失」,持久绑定被清掉。
+ */
+export function shouldClearMissingParent(boundParentId, parentId, resolvable) {
+    return parentId !== '' && boundParentId === parentId && !resolvable;
+}
+/**
+ * 删除锚点前收集以它为父级的子锚点(连同世界定格),交给
+ * anchorsRegistry.removeAnchor 折进删除的同一事务(同
+ * collectBoundCameraResets 对路径删除的作用;撤销陷阱见
+ * pathRegistry.removePathFromRegistry 注释)。
+ *
+ * 只探测不创建:子锚点对象经内部对象表 peek(getObject 不创建),
+ * 世界定格读运行时登记表(anchorObjects)的节点。节点缺失(未挂载)
+ * 的子锚点跳过——局部偏移没有世界定格可写,持久绑定留给挂载后的
+ * 重试/看护处理。
+ */
+export function collectAnchorChildResets(sheet, parentKey) {
+    const parentId = makeTargetId('anchor', parentKey);
+    const resets = [];
+    for (const key of readAnchorKeys(getAnchorsRegistry(sheet))) {
+        if (key === parentKey)
+            continue;
+        const node = anchorObjects.get(key);
+        if (!node)
+            continue;
+        const internal = privateAPI(sheet).getObject(key);
+        const obj = (internal?.publicApi ?? undefined);
+        if (!obj)
+            continue;
+        const parent = val(obj.props.parent) ?? '';
+        if (parent !== parentId)
+            continue;
+        const world = node.getWorldPosition(new Vector3());
+        resets.push({ obj, freeze: { x: world.x, y: world.y, z: world.z } });
+    }
+    return resets;
+}
+/** 从放置注册表反查模型显示名;放置注册表未建好时回退原 key */
+function placementDisplayName(sheet, placementKey) {
+    try {
+        const entry = readPlacementEntries(sheet).find((e) => e.key === placementKey);
+        if (entry)
+            return entry.key.replace(/^Models \/ /, '');
+    }
+    catch {
+        // 放置注册表尚未创建
+    }
+    return placementKey;
+}

package/dist/aimTargets.test.d.ts

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

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

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

package/dist/aimTargets.test.js

@@ -0,0 +1,84 @@
+// packages/camera-studio/src/aimTargets.test.ts
+import { Object3D } from 'three';
+import { registerMessages, translate } from '@dreamerbird/studio/i18n';
+import { parseTargetId, makeTargetId, resolveTargetObject, registerAnchorObject, getAnchorObjects, aimTargetOptions, } from './aimTargets';
+import { makeBoneAnchorId } from './boneAnchors';
+function emptyLookup() {
+    return {
+        anchors: new Map(),
+        bones: new Map(),
+        models: new Map(),
+        cameras: new Map(),
+    };
+}
+describe('parseTargetId / makeTargetId', () => {
+    test('四种 kind 互逆', () => {
+        expect(parseTargetId('')).toBeNull();
+        expect(makeTargetId('anchor', 'Anchor 1')).toBe('anchor:Anchor 1');
+        expect(parseTargetId('anchor:Anchor 1')).toEqual({
+            kind: 'anchor',
+            key: 'Anchor 1',
+        });
+        expect(makeTargetId('model', 'Models / Y Bot')).toBe('model:Models / Y Bot');
+        expect(parseTargetId('model:Models / Y Bot')).toEqual({
+            kind: 'model',
+            key: 'Models / Y Bot',
+        });
+        expect(makeTargetId('camera', 'Shot Camera / Camera')).toBe('camera:Shot Camera / Camera');
+        expect(parseTargetId('camera:Shot Camera / Camera')).toEqual({
+            kind: 'camera',
+            key: 'Shot Camera / Camera',
+        });
+        const boneId = makeBoneAnchorId('Models / Y Bot', 'head');
+        expect(parseTargetId(boneId)).toEqual({
+            kind: 'bone',
+            placementKey: 'Models / Y Bot',
+            part: 'head',
+        });
+        expect(makeTargetId('bone', 'Models / Y Bot', 'head')).toBe(boneId);
+    });
+    test('坏 id 返回 null', () => {
+        expect(parseTargetId('nonsense')).toBeNull();
+        expect(parseTargetId('anchor:')).toBeNull();
+        expect(parseTargetId('bone:k#nope')).toBeNull();
+    });
+});
+describe('resolveTargetObject', () => {
+    test('按 kind 查对应表;空 id 与解析失败都是 null', () => {
+        const anchorObj = new Object3D();
+        const boneObj = new Object3D();
+        const modelObj = new Object3D();
+        const camObj = new Object3D();
+        const lookup = emptyLookup();
+        lookup.anchors.set('Anchor 1', anchorObj);
+        lookup.bones.set(makeBoneAnchorId('M1', 'handL'), boneObj);
+        lookup.models.set('M1', modelObj);
+        lookup.cameras.set('C1', camObj);
+        expect(resolveTargetObject('', lookup)).toBeNull();
+        expect(resolveTargetObject('anchor:Anchor 1', lookup)).toBe(anchorObj);
+        expect(resolveTargetObject(makeBoneAnchorId('M1', 'handL'), lookup)).toBe(boneObj);
+        expect(resolveTargetObject('model:M1', lookup)).toBe(modelObj);
+        expect(resolveTargetObject('camera:C1', lookup)).toBe(camObj);
+        expect(resolveTargetObject('anchor:不存在', lookup)).toBeNull();
+    });
+});
+describe('registerAnchorObject', () => {
+    test('登记/覆盖/注销(null)', () => {
+        const obj = new Object3D();
+        registerAnchorObject('Anchor 1', obj);
+        expect(getAnchorObjects().get('Anchor 1')).toBe(obj);
+        registerAnchorObject('Anchor 1', null);
+        expect(getAnchorObjects().size).toBe(0);
+    });
+});
+describe('aimTargetOptions', () => {
+    // 选项函数读运行时登记表;此处只验证纯函数层:未注入 sheet 时
+    // 只有「无」一项(锚点/骨骼注册表的读取在注入后才有候选,Task 8
+    // 统一浏览器冒烟)。动态选项组装依赖 studio 面板渲染上下文,
+    // 不进单元测试。
+    test('未注入 sheet 时只有「无」一项', () => {
+        registerMessages('en', { 'pg.props.aimNone': 'None' });
+        registerMessages('zh-CN', { 'pg.props.aimNone': '无' });
+        expect(aimTargetOptions()).toEqual({ '': translate('pg.props.aimNone') });
+    });
+});

package/dist/anchorParenting.test.d.ts

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

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

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