@dreamerbird/camera-studio 0.0.0-stage → 0.1.0

package/dist/poseMode/poseLibResolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poseLibResolve.d.ts","sourceRoot":"","sources":["../../src/poseMode/poseLibResolve.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAA;AAC7C,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,aAAa,CAAA;AAK9C,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAQhE;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,GAAG,IAAI,GAC1B,SAAS,GAAG,IAAI,CAGlB;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,EACrB,OAAO,EAAE,MAAM,IAAI,GAClB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED,gCAAgC;AAChC,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAEtE;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C"}

package/dist/poseMode/poseLibResolve.js

@@ -0,0 +1,49 @@
+/**
+ * 库姿势解析缓存(spec §5)。约束:插值器/求值是同步热路径,库条目读取
+ * (IndexedDB)是异步——同步 Map 缓存 + 异步 prefetch 填充,填充完成由
+ * 调用方 invalidate() 触发重求值;未命中期间回 null(渲染回绑定、
+ * 插值阶跃),每个 id 只告警一次。库姿势条目视为不可变(抽帧存姿势
+ * 总是新建条目),缓存不失效。
+ */
+import { getLibrary } from '../assetLibrary/library';
+const cache = new Map();
+const warned = new Set();
+export function resolveLibPoseBones(id) {
+    const bones = cache.get(id);
+    if (bones)
+        return bones;
+    if (!warned.has(id)) {
+        warned.add(id);
+        console.warn(`[pose] 库姿势 ${id} 未解析(缺失或加载中),回退绑定姿势`);
+    }
+    return null;
+}
+export function resolvePoseBones(value) {
+    if (!value)
+        return null;
+    return value.kind === 'custom' ? value.bones : resolveLibPoseBones(value.id);
+}
+export async function prefetchLibPoses(ids, onReady) {
+    const missing = [...new Set(ids)].filter((id) => !cache.has(id));
+    if (missing.length === 0)
+        return;
+    await Promise.all(missing.map(async (id) => {
+        try {
+            const entry = await getLibrary().getEntry(id);
+            if (entry?.kind === 'pose')
+                cache.set(id, entry.bones);
+        }
+        catch (err) {
+            console.warn('[pose] 库姿势加载失败', id, err);
+        }
+    }));
+    onReady();
+}
+/** 测试与已知好数据(如刚解析过的库面板列表)直填缓存 */
+export function __primeLibPoseCache(id, bones) {
+    cache.set(id, bones);
+}
+export function __resetLibPoseCache() {
+    cache.clear();
+    warned.clear();
+}

package/dist/poseMode/poseLibResolve.test.d.ts

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

package/dist/poseMode/poseLibResolve.test.d.ts.map

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

package/dist/poseMode/poseLibResolve.test.js

@@ -0,0 +1,59 @@
+const bones = { Hips: { rotation: [0, 0, 0, 1], position: [0, 1, 0] } };
+const getEntryMock = jest.fn(async (id) => id === 'inLib' ? { kind: 'pose', id, rig: 'mixamo', bones } : undefined);
+jest.doMock('../assetLibrary/library', () => ({
+    getLibrary: () => ({ getEntry: getEntryMock }),
+}));
+let resolveLibPoseBones;
+let resolvePoseBones;
+let prefetchLibPoses;
+let __primeLibPoseCache;
+let __resetLibPoseCache;
+beforeEach(() => {
+    jest.resetModules();
+    getEntryMock.mockClear();
+    ({
+        resolveLibPoseBones,
+        resolvePoseBones,
+        prefetchLibPoses,
+        __primeLibPoseCache,
+        __resetLibPoseCache,
+    } = require('./poseLibResolve'));
+    __resetLibPoseCache();
+    jest.spyOn(console, 'warn').mockImplementation(() => { });
+});
+afterEach(() => {
+    ;
+    console.warn.mockRestore();
+});
+test('未缓存回 null 且每 id 只告警一次;prime 后命中', () => {
+    expect(resolveLibPoseBones('missing')).toBe(null);
+    expect(resolveLibPoseBones('missing')).toBe(null);
+    expect(console.warn).toHaveBeenCalledTimes(1);
+    __primeLibPoseCache('missing', bones);
+    expect(resolveLibPoseBones('missing')).toBe(bones);
+});
+test('prefetch 拉取缺失条目进缓存并回调 onReady;已缓存不重复拉', async () => {
+    __primeLibPoseCache('inLib', bones);
+    const onReady = jest.fn();
+    await prefetchLibPoses(['inLib', 'absent'], onReady);
+    expect(resolveLibPoseBones('inLib')).toBe(bones);
+    expect(resolveLibPoseBones('absent')).toBe(null);
+    expect(onReady).toHaveBeenCalledTimes(1);
+    // 已缓存的 inLib 不重复拉;absent 拉过但后端无此条目,不入缓存
+    expect(getEntryMock).toHaveBeenCalledTimes(1);
+    expect(getEntryMock).toHaveBeenCalledWith('absent');
+});
+test('prefetch 未缓存的库 id 由后端填充进缓存', async () => {
+    const onReady = jest.fn();
+    await prefetchLibPoses(['inLib'], onReady);
+    expect(resolveLibPoseBones('inLib')).toBe(bones);
+    expect(onReady).toHaveBeenCalledTimes(1);
+});
+test('resolvePoseBones:null→null;custom→bones;lib→缓存或 null', () => {
+    expect(resolvePoseBones(null)).toBe(null);
+    expect(resolvePoseBones({ kind: 'custom', bones })).toBe(bones);
+    expect(resolvePoseBones({ kind: 'lib', id: 'inLib' })).toBe(null); // 未预取
+    __primeLibPoseCache('inLib', bones);
+    expect(resolvePoseBones({ kind: 'lib', id: 'inLib' })).toBe(bones);
+});
+export {};

package/dist/poseMode/poseMigration.d.ts

@@ -0,0 +1,5 @@
+export declare function computeLegacyPoseMigration(legacy: {
+    pose: string;
+    poseOverride: string;
+}): string | null;
+//# sourceMappingURL=poseMigration.d.ts.map

package/dist/poseMode/poseMigration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poseMigration.d.ts","sourceRoot":"","sources":["../../src/poseMode/poseMigration.ts"],"names":[],"mappings":"AAQA,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;CACrB,GAAG,MAAM,GAAG,IAAI,CAKhB"}

package/dist/poseMode/poseMigration.js

@@ -0,0 +1,16 @@
+// packages/camera-studio/src/poseMode/poseMigration.ts
+/**
+ * 旧两字段(props.pose 裸 id / props.poseOverride 骨骼 JSON)迁移为新 pose
+ * 值(spec §9)。覆盖优先;新值已存在不碰;旧值原样搬——读取侧
+ * parsePoseValue 把旧格式容错成新形态,搬家即升级。
+ */
+import { isMigratedPoseValue } from './poseValue';
+export function computeLegacyPoseMigration(legacy) {
+    if (isMigratedPoseValue(legacy.pose))
+        return null;
+    if (legacy.poseOverride.trim())
+        return legacy.poseOverride;
+    if (legacy.pose.trim())
+        return legacy.pose;
+    return null;
+}

package/dist/poseMode/poseMigration.test.d.ts

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

package/dist/poseMode/poseMigration.test.d.ts.map

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

package/dist/poseMode/poseMigration.test.js

@@ -0,0 +1,25 @@
+// packages/camera-studio/src/poseMode/poseMigration.test.ts
+/**
+ * 旧两字段 → 新 pose 值的迁移合成(spec §9):覆盖优先;已是新格式不动;
+ * 双空不迁移。旧值原样搬——读取侧容错(parsePoseValue)完成格式升级。
+ */
+import { computeLegacyPoseMigration } from './poseMigration';
+const legacyBones = JSON.stringify({
+    Hips: { rotation: [0, 0, 0, 1], position: [0, 1, 0] },
+});
+test('已是新格式:不迁移(返回 null)', () => {
+    expect(computeLegacyPoseMigration({
+        pose: '{"kind":"lib","id":"p1"}',
+        poseOverride: legacyBones,
+    })).toBe(null);
+});
+test('覆盖优先:poseOverride 非空时搬 override(旧骨骼 JSON 原样)', () => {
+    expect(computeLegacyPoseMigration({ pose: 'entry_a', poseOverride: legacyBones })).toBe(legacyBones);
+});
+test('仅库姿势:搬旧裸 id 原样', () => {
+    expect(computeLegacyPoseMigration({ pose: 'entry_a', poseOverride: '' })).toBe('entry_a');
+});
+test('双空:不迁移', () => {
+    expect(computeLegacyPoseMigration({ pose: '', poseOverride: '' })).toBe(null);
+    expect(computeLegacyPoseMigration({ pose: '  ', poseOverride: '  ' })).toBe(null);
+});

package/dist/poseMode/poseOptions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 姿势选择弹框的选项组装(属性面板姿势行),纯函数便于单测。
+ * 语义(2026-10-01 与用户对齐):弹框 = 纯姿势列表——「T 姿势」
+ * (绑定/默认)永远第一项,往下是库预设(骨架族过滤置灰);自定义
+ * 姿势不是弹框选项,只能双击模型进姿势模式编辑产生,但 current
+ * 会如实报 'custom'(列表里无对应高亮项)。当前值引用已删除的
+ * 库条目时追加置灰缺失项如实显示。
+ */
+import type { PoseEntry } from '../assetLibrary/types';
+export type PoseOptionKey = 'bind' | `lib:${string}`;
+/** 当前状态:custom 没有对应弹框选项,仅作状态上报 */
+export type PoseCurrentKey = PoseOptionKey | 'custom';
+export type PoseOption = {
+    key: PoseOptionKey;
+    label: string;
+    disabled?: boolean;
+    hint?: string;
+    /** 缩略图 URL(条目带 thumbnailId 且解析完成时由调用方注入) */
+    thumbUrl?: string;
+};
+export declare function buildPoseOptions(args: {
+    /** 当前 pose 属性值(JSON 字符串,''=绑定/T 姿势) */
+    poseJson: string;
+    libEntries: Pick<PoseEntry, 'id' | 'name' | 'rig' | 'thumbnailId'>[];
+    /** 当前选中模型的骨架族;缺省=不过滤 */
+    selectedRig?: string;
+    /** 缩略图 URL 解析(懒加载 hook 的 getThumbUrl);缺省=无图 */
+    thumbUrlOf?: (entry: {
+        id: string;
+        thumbnailId?: string;
+    }) => string | undefined;
+    /** 「T 姿势」项的缩略图(2026-10-05):调用方传当前选中模型自己的
+        缩略图——模型图就是按绑定/T 姿势渲染的,语义正好 */
+    bindThumbUrl?: string;
+    /** 显示名解析(poseEntryName:种子条目查 i18n 词典);缺省=条目名原文 */
+    nameOf?: (entry: {
+        id: string;
+        name: string;
+    }) => string;
+    t: (k: string) => string;
+}): {
+    options: PoseOption[];
+    current: PoseCurrentKey;
+};
+//# sourceMappingURL=poseOptions.d.ts.map

package/dist/poseMode/poseOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poseOptions.d.ts","sourceRoot":"","sources":["../../src/poseMode/poseOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAA;AAGpD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,MAAM,EAAE,CAAA;AACpD,kCAAkC;AAClC,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,QAAQ,CAAA;AAErD,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,aAAa,CAAA;IAClB,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,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,KAAK,GAAG,aAAa,CAAC,EAAE,CAAA;IACpE,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;qCACiC;IACjC,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,UAAU,EAAE,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAC,CAkDnD"}

package/dist/poseMode/poseOptions.js

@@ -0,0 +1,39 @@
+import { parsePoseValue } from './poseValue';
+export function buildPoseOptions(args) {
+    const { poseJson, libEntries, selectedRig, thumbUrlOf, bindThumbUrl, nameOf, t, } = args;
+    const currentValue = parsePoseValue(poseJson);
+    const current = !currentValue
+        ? 'bind'
+        : currentValue.kind === 'custom'
+            ? 'custom'
+            : `lib:${currentValue.id}`;
+    const options = [
+        {
+            key: 'bind',
+            label: t('pg.pose.tPose'),
+            ...(bindThumbUrl ? { thumbUrl: bindThumbUrl } : {}),
+        },
+    ];
+    for (const entry of libEntries) {
+        const rigMismatch = selectedRig !== undefined && entry.rig !== selectedRig;
+        const thumbUrl = thumbUrlOf?.(entry);
+        options.push({
+            key: `lib:${entry.id}`,
+            label: nameOf?.(entry) ?? entry.name,
+            disabled: rigMismatch || undefined,
+            hint: rigMismatch ? t('pg.lib.rigMismatch') : undefined,
+            ...(thumbUrl ? { thumbUrl } : {}),
+        });
+    }
+    // 当前值引用的库条目已不在库里(被删/多端缺条目):追加置灰缺失项
+    if (currentValue?.kind === 'lib' &&
+        !libEntries.some((e) => e.id === currentValue.id)) {
+        options.push({
+            key: `lib:${currentValue.id}`,
+            label: currentValue.id,
+            disabled: true,
+            hint: t('pg.pose.libMissing'),
+        });
+    }
+    return { options, current };
+}

package/dist/poseMode/poseOptions.test.d.ts

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

package/dist/poseMode/poseOptions.test.d.ts.map

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

package/dist/poseMode/poseOptions.test.js

@@ -0,0 +1,83 @@
+/**
+ * 姿势选择弹框的选项组装(属性面板姿势行):纯函数便于单测。
+ * 规则(2026-10-01 与用户对齐):
+ * - 「T 姿势」(绑定/默认)永远第一项——弹框就是纯姿势列表;
+ * - 自定义姿势不是弹框选项(只能双击模型进姿势模式编辑产生),
+ *   但 current 仍会如实报 'custom'(列表里无对应高亮项);
+ * - 库预设按骨架族过滤,不匹配的置灰带提示;
+ * - 当前值是已被删除的库条目时,追加一个置灰缺失项如实显示现状。
+ */
+import { buildPoseOptions } from './poseOptions';
+import { serializeCustomPose, serializeLibPose } from './poseValue';
+const t = (k) => `#${k}#`;
+const libEntries = [
+    { id: 'lib-wave', name: '挥手', rig: 'mixamo' },
+    { id: 'lib-sit', name: '坐下', rig: 'mixamo' },
+    { id: 'lib-vrm1', name: 'VRM 万岁', rig: 'vrm' },
+];
+test('空值(绑定):T 姿势第一项,当前 bind;无任何 custom 选项', () => {
+    const { options, current } = buildPoseOptions({ poseJson: '', libEntries, t });
+    expect(current).toBe('bind');
+    expect(options.map((o) => o.key)).toEqual([
+        'bind',
+        'lib:lib-wave',
+        'lib:lib-sit',
+        'lib:lib-vrm1',
+    ]);
+    expect(options[0].label).toBe('#pg.pose.tPose#');
+});
+test('当前是库姿势:current 指向该条目', () => {
+    const { current } = buildPoseOptions({
+        poseJson: serializeLibPose('lib-wave'),
+        libEntries,
+        t,
+    });
+    expect(current).toBe('lib:lib-wave');
+});
+test('当前是自定义:current 报 custom,但选项里没有 custom 项', () => {
+    const { options, current } = buildPoseOptions({
+        poseJson: serializeCustomPose({ Hips: { rotation: [0, 0, 0, 1] } }),
+        libEntries,
+        t,
+    });
+    expect(current).toBe('custom');
+    expect(options.map((o) => o.key)).not.toContain('custom');
+});
+test('骨架不匹配:置灰并带提示;无骨架信息不过滤', () => {
+    const { options } = buildPoseOptions({
+        poseJson: '',
+        libEntries,
+        selectedRig: 'mixamo',
+        t,
+    });
+    const vrm = options.find((o) => o.key === 'lib:lib-vrm1');
+    const wave = options.find((o) => o.key === 'lib:lib-wave');
+    expect(vrm.disabled).toBe(true);
+    expect(vrm.hint).toBeTruthy();
+    expect(wave.disabled).toBeFalsy();
+});
+test('当前库条目已被删除:追加置灰缺失项作为当前显示', () => {
+    const { options, current } = buildPoseOptions({
+        poseJson: serializeLibPose('lib-gone'),
+        libEntries,
+        t,
+    });
+    expect(current).toBe('lib:lib-gone');
+    const missing = options.find((o) => o.key === 'lib:lib-gone');
+    expect(missing.disabled).toBe(true);
+    expect(missing.hint).toBeTruthy();
+});
+test('「T 姿势」项挂 bindThumbUrl(模型自己的图);不传则无图', () => {
+    const withThumb = buildPoseOptions({
+        poseJson: '',
+        libEntries,
+        bindThumbUrl: 'blob:model-thumb',
+        t,
+    });
+    expect(withThumb.options[0]).toMatchObject({
+        key: 'bind',
+        thumbUrl: 'blob:model-thumb',
+    });
+    const without = buildPoseOptions({ poseJson: '', libEntries, t });
+    expect(without.options[0].thumbUrl).toBeUndefined();
+});

package/dist/poseMode/poseOverride.d.ts

@@ -0,0 +1,13 @@
+/**
+ * poseOverride:摆姿势退出时内联写进 theatre 对象的骨骼状态(JSON 字符串)。
+ * 优先级高于库姿势 poseId、低于什么都不写的绑定姿势兜底:
+ *   effectivePoseBones = poseOverride ?? 库姿势 ?? 绑定姿势
+ * 刷新/撤销重做/多端同步都走 theatre 属性通道,无需额外处理。
+ */
+import type { PoseEntry } from '../assetLibrary/types';
+export type PoseBones = PoseEntry['bones'];
+export declare function stringifyPoseOverride(bones: PoseBones): string;
+/** 空串/坏 JSON/非对象都回 null(手改坏或同步损坏时回退库姿势,不崩画布) */
+export declare function parsePoseOverride(json: string): PoseBones | null;
+export declare function effectivePoseBones(overrideJson: string, poseBones: PoseBones | null, bindPose: PoseBones): PoseBones;
+//# sourceMappingURL=poseOverride.d.ts.map

package/dist/poseMode/poseOverride.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poseOverride.d.ts","sourceRoot":"","sources":["../../src/poseMode/poseOverride.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AACH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAA;AAEpD,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,CAAA;AAE1C,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAE9D;AAID,gDAAgD;AAChD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAiBhE;AAED,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,SAAS,GAAG,IAAI,EAC3B,QAAQ,EAAE,SAAS,GAClB,SAAS,CAEX"}

package/dist/poseMode/poseOverride.js

@@ -0,0 +1,26 @@
+export function stringifyPoseOverride(bones) {
+    return JSON.stringify(bones);
+}
+let warned = false;
+/** 空串/坏 JSON/非对象都回 null(手改坏或同步损坏时回退库姿势,不崩画布) */
+export function parsePoseOverride(json) {
+    if (!json)
+        return null;
+    try {
+        const parsed = JSON.parse(json);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        if (!warned) {
+            warned = true;
+            console.warn('[poseMode] poseOverride JSON 解析失败,回退到库姿势/绑定姿势');
+        }
+        return null;
+    }
+}
+export function effectivePoseBones(overrideJson, poseBones, bindPose) {
+    return parsePoseOverride(overrideJson) ?? poseBones ?? bindPose;
+}

package/dist/poseMode/poseOverride.test.d.ts

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

package/dist/poseMode/poseOverride.test.d.ts.map

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

package/dist/poseMode/poseOverride.test.js

@@ -0,0 +1,23 @@
+import { effectivePoseBones, parsePoseOverride, stringifyPoseOverride, } from './poseOverride';
+const bonesA = {
+    Hips: { rotation: [0, 0, 0, 1], position: [0, 1, 0] },
+};
+const bonesB = {
+    Head: { rotation: [0, 0, 0, 1], position: [0, 1.6, 0] },
+};
+const bind = {
+    Root: { rotation: [0, 0, 0, 1], position: [0, 0, 0] },
+};
+test('stringify/parse 往返一致', () => {
+    expect(parsePoseOverride(stringifyPoseOverride(bonesA))).toEqual(bonesA);
+});
+test('空串与坏 JSON 都返回 null', () => {
+    expect(parsePoseOverride('')).toBeNull();
+    expect(parsePoseOverride('{oops')).toBeNull();
+    expect(parsePoseOverride('123')).toBeNull();
+});
+test('优先级:poseOverride > 库姿势 > 绑定姿势', () => {
+    expect(effectivePoseBones('', null, bind)).toBe(bind);
+    expect(effectivePoseBones('', bonesB, bind)).toBe(bonesB);
+    expect(effectivePoseBones(stringifyPoseOverride(bonesA), bonesB, bind)).toEqual(bonesA);
+});

package/dist/poseMode/poseRetarget.d.ts

@@ -0,0 +1,17 @@
+import type { PoseBones } from './poseOverride';
+export type RestBone = {
+    name: string;
+    /** 父骨名;根骨为 null(其父链为非骨节点,世界基准由 worldQuat 反推) */
+    parent: string | null;
+    /** rest local 四元数 [x,y,z,w] */
+    localQuat: [number, number, number, number];
+    /** rest 世界四元数(含全部父链,含非骨祖先) [x,y,z,w] */
+    worldQuat: [number, number, number, number];
+};
+/**
+ * @param restBones - 目标骨架 rest 快照,根到叶序
+ * @param dirs - 骨名 → 目标世界 Y 轴方向(three.js 系,无需归一化)
+ * @returns PoseBones(覆盖 restBones 全部骨;dirs 里的多余骨名忽略)
+ */
+export declare function retargetPose(restBones: RestBone[], dirs: Record<string, [number, number, number]>): PoseBones;
+//# sourceMappingURL=poseRetarget.d.ts.map

package/dist/poseMode/poseRetarget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poseRetarget.d.ts","sourceRoot":"","sources":["../../src/poseMode/poseRetarget.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAA;AAE7C,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,gDAAgD;IAChD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,+BAA+B;IAC/B,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3C,wCAAwC;IACxC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAC5C,CAAA;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,QAAQ,EAAE,EACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,GAC7C,SAAS,CA0BX"}

package/dist/poseMode/poseRetarget.js

@@ -0,0 +1,53 @@
+// packages/camera-studio/src/poseMode/poseRetarget.ts
+/**
+ * 姿势重定向(2026-10-02 内置姿势管线,机制经 spike 验证):
+ * 把「每根骨的世界 Y 轴目标方向」换算成目标骨架的 local 四元数快照。
+ *
+ * 为什么不直接搬 local:不同骨架/不同工具链(Blender↔FBX↔three)对同一
+ * 骨骼的 local 表示不同(骨轴约定),直接搬必拧;世界骨向是表示无关的
+ * 共同语言。换算规则(最短弧):
+ *   newWorldQ = setFromUnitVectors(restWorldY → targetDir) × restWorldQ
+ * 即「从 rest 骨向最短弧转到目标方向,roll 保 rest 关系」。代价是丢源骨
+ * 的 roll 变化(手臂内旋等),姿势库场景可接受——换来对任意 roll 差异
+ * (实测大腿/脚两骨架差 ~180°)不拧麻花。
+ *
+ * 层级:输入 restBones 必须根到叶序。dirs 没给方向的骨随父(local 保
+ * rest,世界随父链新姿势)。输出覆盖 restBones 全部骨——库姿势应用时
+ * 全身确定,切换姿势无残留(见 pose.ts applyPose 只写列出的骨)。
+ *
+ * 纯函数无 DOM 依赖:jest 与 node 构建脚本(scripts/pose-pipeline)共用。
+ */
+import { Quaternion, Vector3 } from 'three';
+/**
+ * @param restBones - 目标骨架 rest 快照,根到叶序
+ * @param dirs - 骨名 → 目标世界 Y 轴方向(three.js 系,无需归一化)
+ * @returns PoseBones(覆盖 restBones 全部骨;dirs 里的多余骨名忽略)
+ */
+export function retargetPose(restBones, dirs) {
+    const newWorldQ = new Map();
+    const out = {};
+    for (const b of restBones) {
+        const restWorld = new Quaternion(...b.worldQuat);
+        // 根骨的父世界:rest 时 worldQ × localQ⁻¹,换算全程不变(非骨祖先不动)
+        const parentWorld = b.parent
+            ? newWorldQ.get(b.parent)
+            : restWorld.clone().multiply(new Quaternion(...b.localQuat).invert());
+        let worldQ;
+        const dir = dirs[b.name];
+        if (dir) {
+            const restY = new Vector3(0, 1, 0).applyQuaternion(restWorld).normalize();
+            const target = new Vector3(...dir).normalize();
+            worldQ = new Quaternion()
+                .setFromUnitVectors(restY, target)
+                .multiply(restWorld);
+        }
+        else {
+            // 随父:世界 = 新父世界 × rest local
+            worldQ = parentWorld.clone().multiply(new Quaternion(...b.localQuat));
+        }
+        newWorldQ.set(b.name, worldQ);
+        const local = parentWorld.clone().invert().multiply(worldQ);
+        out[b.name] = { rotation: [local.x, local.y, local.z, local.w] };
+    }
+    return out;
+}

package/dist/poseMode/poseRetarget.test.d.ts

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

package/dist/poseMode/poseRetarget.test.d.ts.map

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

package/dist/poseMode/poseRetarget.test.js

@@ -0,0 +1,88 @@
+// packages/camera-studio/src/poseMode/poseRetarget.test.ts
+import { Quaternion, Vector3 } from 'three';
+import { retargetPose } from './poseRetarget';
+const Q0 = [0, 0, 0, 1];
+/** 构造 rest 快照:全单位 local,父链决定世界 */
+function bone(name, parent, localQuat = Q0, worldQuat = Q0) {
+    return { name, parent, localQuat, worldQuat };
+}
+function worldYOf(q) {
+    return new Vector3(0, 1, 0).applyQuaternion(new Quaternion(...q)).normalize();
+}
+describe('retargetPose', () => {
+    it('方向全给 rest 骨向时输出恒等(全骨 local=rest local)', () => {
+        const rest = [bone('hips', null), bone('head', 'hips')];
+        const dirs = {
+            hips: [0, 1, 0],
+            head: [0, 1, 0],
+        };
+        const out = retargetPose(rest, dirs);
+        // 全单位 rest + 方向即 rest 骨向 → 每骨 local 仍为单位(w≈1,xyz≈0)
+        for (const name of ['hips', 'head']) {
+            expect(out[name].rotation[3]).toBeCloseTo(1, 5);
+            expect(out[name].rotation[0]).toBeCloseTo(0, 5);
+        }
+    });
+    it('单链根骨转 90°:根 local=弧,子 local 保 rest,子世界随父', () => {
+        const rest = [bone('hips', null), bone('arm', 'hips')];
+        // rest 世界 Y = (0,1,0),目标 (1,0,0):绕 Z 轴 -90°
+        const out = retargetPose(rest, { hips: [1, 0, 0] });
+        const rootQ = new Quaternion(...out.hips.rotation);
+        // 根的世界 Y 应指向 (1,0,0)
+        const rootWorldY = worldYOf(out.hips.rotation);
+        expect(rootWorldY.x).toBeCloseTo(1, 5);
+        expect(rootWorldY.y).toBeCloseTo(0, 5);
+        // 子 local 保 rest(单位)
+        expect(out.arm.rotation[3]).toBeCloseTo(1, 5);
+        // 子世界 = 根世界 × 子 local = 根世界
+        const childWorld = rootQ
+            .clone()
+            .multiply(new Quaternion(...out.arm.rotation));
+        const childWorldY = new Vector3(0, 1, 0).applyQuaternion(childWorld);
+        expect(childWorldY.x).toBeCloseTo(1, 5);
+    });
+    it('带旋转的 rest:换算后世界骨向精确命中目标方向', () => {
+        // rest 根骨绕 Z 转 45°,世界 Y = (sin45, cos45, 0)
+        const restRootQ = new Quaternion().setFromAxisAngle(new Vector3(0, 0, 1), -Math.PI / 4);
+        const rest = [
+            {
+                name: 'hips',
+                parent: null,
+                localQuat: [restRootQ.x, restRootQ.y, restRootQ.z, restRootQ.w],
+                worldQuat: [restRootQ.x, restRootQ.y, restRootQ.z, restRootQ.w],
+            },
+        ];
+        const out = retargetPose(rest, { hips: [0, 0, 1] });
+        const gotY = worldYOf(out.hips.rotation);
+        expect(gotY.x).toBeCloseTo(0, 5);
+        expect(gotY.y).toBeCloseTo(0, 5);
+        expect(gotY.z).toBeCloseTo(1, 5);
+    });
+    it('dirs 里的未知骨名被忽略,输出仍覆盖 rest 全骨', () => {
+        const rest = [bone('hips', null)];
+        const out = retargetPose(rest, { nope: [1, 0, 0] });
+        expect(Object.keys(out)).toEqual(['hips']);
+        expect(out.hips.rotation[3]).toBeCloseTo(1, 5);
+    });
+    it('三级链中间骨动:末端随动但 local 不变', () => {
+        const rest = [
+            bone('hips', null),
+            bone('thigh', 'hips'),
+            bone('shin', 'thigh'),
+        ];
+        const out = retargetPose(rest, { thigh: [0, -0.7, 0.7] });
+        // thigh 世界 Y 命中
+        const thighWorld = new Quaternion(...out.thigh.rotation);
+        const thighY = new Vector3(0, 1, 0).applyQuaternion(thighWorld).normalize();
+        expect(thighY.y).toBeCloseTo(-0.7071, 3);
+        expect(thighY.z).toBeCloseTo(0.7071, 3);
+        // shin local 保 rest
+        expect(out.shin.rotation[3]).toBeCloseTo(1, 5);
+        // shin 世界 = thigh 世界 × shin local → 世界 Y 同 thigh
+        const shinWorld = thighWorld
+            .clone()
+            .multiply(new Quaternion(...out.shin.rotation));
+        const shinY = new Vector3(0, 1, 0).applyQuaternion(shinWorld).normalize();
+        expect(shinY.y).toBeCloseTo(-0.7071, 3);
+    });
+});