@dreamerbird/camera-studio 0.2.0 → 0.3.0

package/dist/poses.js

@@ -0,0 +1,41 @@
+/**
+ * 内置静态姿势库的公开入口(包根与 `@dreamerbird/camera-studio/poses`
+ * 子路径同时导出)。
+ *
+ * 姿势数据随包编译进 JS,不依赖 IndexedDB / 网络 / React。引用本包的
+ * 项目可以直接列出姿势、把 `entry.bones` 写进自己的 THREE 骨架,或交给
+ * Agent API 的 `poses.applyCustom`。
+ *
+ * - id 稳定:`seed-pose-<key>`,与场景里已保存的姿势引用一致。
+ * - rig 是内置族代表模型(Y Bot)的 Mixamo 骨架 id;导入同款 Mixamo
+ *   模型得到的 rig 与之相等,跨项目可直接复用。
+ * - QBX 手势条目只包含手指骨,是叠加片段,不覆盖身体姿势。
+ */
+import { applyPose, captureBindPose, capturePose } from './assetLibrary/pose';
+import { buildBuiltinPoseEntries, builtinPoseRig, } from './assetLibrary/seedBuiltinPoses';
+export { applyPose, captureBindPose, capturePose };
+/** 内置姿势所属骨架族(内置 Y Bot 的 rig id) */
+export const BUILTIN_POSE_RIG = builtinPoseRig();
+/** 内置姿势数据来源,用于署名/展示;不影响运行时行为 */
+export const BUILTIN_POSE_SOURCES = [
+    { id: 'procedural', name: '内置程序化基础姿势' },
+    { id: 'dpl', name: 'Dynamic Pose Library Free (BlendAtlas)' },
+    { id: 'qbx', name: 'QBX Pose Asset Pack' },
+];
+let entriesById;
+/**
+ * 列出全部内置静态姿势。返回的条目是包内共享的只读数据,请勿原地修改;
+ * 需要改骨骼时先拷贝 `bones`。
+ */
+export function listBuiltinPoses() {
+    if (!entriesById) {
+        const entries = buildBuiltinPoseEntries(BUILTIN_POSE_RIG);
+        entriesById = new Map(entries.map((entry) => [entry.id, entry]));
+    }
+    return [...entriesById.values()];
+}
+/** 按稳定 id 取内置姿势;未知 id 返回 undefined。 */
+export function getBuiltinPose(id) {
+    listBuiltinPoses();
+    return entriesById.get(id);
+}

package/dist/poses.test.d.ts

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

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

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

package/dist/poses.test.js

@@ -0,0 +1,38 @@
+import { Bone, Object3D } from 'three';
+import { applyPose, BUILTIN_POSE_RIG, getBuiltinPose, listBuiltinPoses, } from './poses';
+describe('内置静态姿势公开 API', () => {
+    test('条目 id 稳定、唯一,并且都属于内置骨架族', () => {
+        const poses = listBuiltinPoses();
+        expect(poses.length).toBeGreaterThan(100);
+        expect(new Set(poses.map((p) => p.id)).size).toBe(poses.length);
+        for (const pose of poses) {
+            expect(pose.kind).toBe('pose');
+            expect(pose.id.startsWith('seed-pose-')).toBe(true);
+            expect(pose.name.length).toBeGreaterThan(0);
+            expect(pose.rig).toBe(BUILTIN_POSE_RIG);
+        }
+    });
+    test('按稳定 id 取姿势;未知 id 返回 undefined', () => {
+        const pose = getBuiltinPose('seed-pose-stand-relaxed');
+        expect(pose?.name).toBe('站立放松');
+        expect(pose?.bones.mixamorigHips.rotation).toHaveLength(4);
+        expect(getBuiltinPose('seed-pose-does-not-exist')).toBeUndefined();
+    });
+    test('手势条目只含手指骨,不会覆盖身体', () => {
+        const gesture = getBuiltinPose('seed-pose-qbx-hands-02-other-fist-l');
+        expect(gesture).toBeDefined();
+        const finger = /^mixamorig(Left|Right)Hand(Thumb|Index|Middle|Ring|Pinky)\d$/;
+        expect(Object.keys(gesture.bones).every((name) => finger.test(name))).toBe(true);
+    });
+    test('applyPose 按骨骼名写入,缺失骨计入 missed', () => {
+        const root = new Object3D();
+        const hips = new Bone();
+        hips.name = 'mixamorigHips';
+        root.add(hips);
+        const pose = getBuiltinPose('seed-pose-stand-relaxed');
+        const result = applyPose(root, pose.bones);
+        expect(result.applied).toBe(1);
+        expect(result.missed).toHaveLength(Object.keys(pose.bones).length - 1);
+        expect(hips.quaternion.toArray()).toEqual(pose.bones.mixamorigHips.rotation);
+    });
+});

package/dist/primitives.d.ts

@@ -0,0 +1,5 @@
+import { Mesh } from 'three';
+export type PrimitiveKind = 'plane' | 'box' | 'sphere' | 'cylinder';
+export declare const PRIMITIVE_KINDS: readonly ["plane", "box", "sphere", "cylinder"];
+export declare function createPrimitive(kind: PrimitiveKind): Mesh;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,IAAI,EAIL,MAAM,OAAO,CAAA;AAEd,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,UAAU,CAAA;AACnE,eAAO,MAAM,eAAe,iDAAkD,CAAA;AAE9E,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAYzD"}

package/dist/primitives.js

@@ -0,0 +1,15 @@
+import { BoxGeometry, CylinderGeometry, Mesh, MeshStandardMaterial, PlaneGeometry, SphereGeometry, } from 'three';
+export const PRIMITIVE_KINDS = ['plane', 'box', 'sphere', 'cylinder'];
+export function createPrimitive(kind) {
+    const geometry = {
+        plane: () => new PlaneGeometry(2, 2),
+        box: () => new BoxGeometry(1, 1, 1),
+        sphere: () => new SphereGeometry(0.5, 32, 16),
+        cylinder: () => new CylinderGeometry(0.5, 0.5, 1, 32),
+    }[kind]();
+    const mesh = new Mesh(geometry, new MeshStandardMaterial({ color: '#b8b8b8' }));
+    mesh.name = `Primitive/${kind}`;
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    return mesh;
+}

package/dist/primitives.test.d.ts

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

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

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

package/dist/primitives.test.js

@@ -0,0 +1,27 @@
+import { BoxGeometry, CylinderGeometry, PlaneGeometry, SphereGeometry, } from 'three';
+import { createPrimitive } from './primitives';
+test('creates the four metric primitive kinds', () => {
+    expect(createPrimitive('plane').geometry).toBeInstanceOf(PlaneGeometry);
+    expect(createPrimitive('box').geometry).toBeInstanceOf(BoxGeometry);
+    expect(createPrimitive('sphere').geometry).toBeInstanceOf(SphereGeometry);
+    expect(createPrimitive('cylinder').geometry).toBeInstanceOf(CylinderGeometry);
+});
+test('uses the specified metric dimensions and tessellation', () => {
+    const plane = createPrimitive('plane').geometry;
+    const box = createPrimitive('box').geometry;
+    const sphere = createPrimitive('sphere').geometry;
+    const cylinder = createPrimitive('cylinder').geometry;
+    expect(plane.parameters).toMatchObject({ width: 2, height: 2 });
+    expect(box.parameters).toMatchObject({ width: 1, height: 1, depth: 1 });
+    expect(sphere.parameters).toMatchObject({
+        radius: 0.5,
+        widthSegments: 32,
+        heightSegments: 16,
+    });
+    expect(cylinder.parameters).toMatchObject({
+        radiusTop: 0.5,
+        radiusBottom: 0.5,
+        height: 1,
+        radialSegments: 32,
+    });
+});

package/dist/reset.realStudio.test.d.ts

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

package/dist/reset.realStudio.test.d.ts.map

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

package/dist/reset.realStudio.test.js

@@ -0,0 +1,60 @@
+/*
+ * @jest-environment node
+ */
+import { types as t, val } from '@dreamerbird/core';
+import { globals } from '@dreamerbird/core/globals';
+import { getCoreRafDriver } from '@dreamerbird/core/coreTicker';
+import getStudio from '@dreamerbird/studio/getStudio';
+jest.doMock('jose', () => ({ decodeJwt: jest.fn() }));
+let bootstrap;
+let renderSpy;
+beforeAll(async () => {
+    bootstrap = await import('./bootstrap');
+    renderSpy = jest.spyOn(getStudio().ui, 'render').mockImplementation(() => { });
+});
+afterAll(() => {
+    renderSpy.mockRestore();
+    getCoreRafDriver().stop?.();
+});
+function sceneState(value) {
+    return {
+        definitionVersion: globals.currentProjectStateDefinitionVersion,
+        sheetsById: {
+            Scene: {
+                staticOverrides: { byObject: { Only: { value } } },
+                sequence: {
+                    type: 'PositionalSequence',
+                    length: 10,
+                    subUnitsPerUnit: 30,
+                    tracksByObject: {},
+                },
+            },
+        },
+    };
+}
+test('reset restores a same-named project from its new initialState with real core/studio', async () => {
+    const projectId = 'camera-studio-reset-real';
+    const first = await bootstrap.initCameraStudio({
+        project: projectId,
+        storage: false,
+        state: { initialState: sceneState(1), onStateChange: () => { } },
+    });
+    const firstProject = first.sceneProps.project;
+    await firstProject.ready;
+    expect(val(firstProject.sheet('Scene').object('Only', { value: t.number(0) }).props
+        .value)).toBe(1);
+    await bootstrap.disposeCameraStudio(first);
+    await bootstrap.resetCameraStudio();
+    const second = await bootstrap.initCameraStudio({
+        project: projectId,
+        storage: false,
+        state: { initialState: sceneState(2), onStateChange: () => { } },
+    });
+    const secondProject = second.sceneProps.project;
+    await secondProject.ready;
+    expect(secondProject).not.toBe(firstProject);
+    expect(val(secondProject.sheet('Scene').object('Only', { value: t.number(0) }).props
+        .value)).toBe(2);
+    await bootstrap.disposeCameraStudio(second);
+    await bootstrap.resetCameraStudio();
+});

package/dist/studioRoot.d.ts

@@ -0,0 +1,4 @@
+export declare function resetStudioRootCache(): void;
+export declare function mountStudioRoot(container?: HTMLElement): HTMLElement | undefined;
+export declare function mountStudioRootWhenReady(container?: HTMLElement): Promise<HTMLElement | undefined>;
+//# sourceMappingURL=studioRoot.d.ts.map

package/dist/studioRoot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"studioRoot.d.ts","sourceRoot":"","sources":["../src/studioRoot.ts"],"names":[],"mappings":"AAUA,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,wBAAgB,eAAe,CAC7B,SAAS,CAAC,EAAE,WAAW,GACtB,WAAW,GAAG,SAAS,CAczB;AAED,wBAAsB,wBAAwB,CAC5C,SAAS,CAAC,EAAE,WAAW,GACtB,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAQlC"}

package/dist/studioRoot.js

@@ -0,0 +1,36 @@
+let retainedRoot;
+/** 纯 Node/SSR 没有 DOM:挂载流程应直接跳过,而不是轮询等待。 */
+function hasDom() {
+    return (typeof document !== 'undefined' &&
+        typeof document.getElementById === 'function');
+}
+export function resetStudioRootCache() {
+    retainedRoot = undefined;
+}
+export function mountStudioRoot(container) {
+    if (!hasDom())
+        return undefined;
+    const root = document.getElementById('theatrejs-studio-root') ?? retainedRoot;
+    if (!root)
+        return undefined;
+    retainedRoot = root;
+    const target = container ?? document.body;
+    target.appendChild(root);
+    const embedded = target !== document.body;
+    root.style.position = embedded ? 'absolute' : 'fixed';
+    root.style.inset = '0';
+    root.style.transform = embedded ? 'translateZ(0)' : '';
+    root.style.zIndex = embedded ? '40' : '100';
+    return root;
+}
+export async function mountStudioRootWhenReady(container) {
+    if (!hasDom())
+        return undefined;
+    for (let attempt = 0; attempt < 3000; attempt += 1) {
+        const root = mountStudioRoot(container);
+        if (root)
+            return root;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    return undefined;
+}

package/dist/studioRoot.test.d.ts

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

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

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

package/dist/studioRoot.test.js

@@ -0,0 +1,62 @@
+/*
+ * @jest-environment jsdom
+ */
+import { mountStudioRoot, mountStudioRootWhenReady, resetStudioRootCache, } from './studioRoot';
+function createStudioRoot() {
+    const root = document.createElement('div');
+    root.id = 'theatrejs-studio-root';
+    root.style.position = 'fixed';
+    root.style.inset = '0';
+    document.body.appendChild(root);
+    return root;
+}
+afterEach(() => {
+    resetStudioRootCache();
+    document.body.innerHTML = '';
+});
+test('mountStudioRoot scopes fixed Studio panels to the host editor', () => {
+    const root = createStudioRoot();
+    const editor = document.createElement('main');
+    document.body.appendChild(editor);
+    expect(mountStudioRoot(editor)).toBe(root);
+    expect(root.parentElement).toBe(editor);
+    expect(root.style.position).toBe('absolute');
+    expect(root.style.inset).toBe('0');
+    expect(root.style.transform).toBe('translateZ(0)');
+    expect(root.style.zIndex).toBe('40');
+});
+test('mountStudioRoot restores the default viewport mounting', () => {
+    const root = createStudioRoot();
+    const editor = document.createElement('main');
+    document.body.appendChild(editor);
+    mountStudioRoot(editor);
+    mountStudioRoot();
+    expect(root.parentElement).toBe(document.body);
+    expect(root.style.position).toBe('fixed');
+    expect(root.style.transform).toBe('');
+    expect(root.style.zIndex).toBe('100');
+});
+test('mountStudioRoot is a no-op before Studio creates its root', () => {
+    expect(mountStudioRoot(document.createElement('main'))).toBeUndefined();
+});
+test('mountStudioRootWhenReady waits for the asynchronously appended root', async () => {
+    const editor = document.createElement('main');
+    document.body.appendChild(editor);
+    const mounted = mountStudioRootWhenReady(editor);
+    setTimeout(createStudioRoot, 10);
+    const root = await mounted;
+    expect(root?.parentElement).toBe(editor);
+    expect(root?.style.position).toBe('absolute');
+});
+test('mountStudioRoot remounts a root retained from an unmounted editor', () => {
+    const root = createStudioRoot();
+    const firstEditor = document.createElement('main');
+    document.body.appendChild(firstEditor);
+    mountStudioRoot(firstEditor);
+    firstEditor.remove();
+    const secondEditor = document.createElement('main');
+    document.body.appendChild(secondEditor);
+    expect(mountStudioRoot(secondEditor)).toBe(root);
+    expect(root.parentElement).toBe(secondEditor);
+    expect(root.isConnected).toBe(true);
+});

package/dist/useCameraStudio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCameraStudio.d.ts","sourceRoot":"","sources":["../src/useCameraStudio.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,kBAAkB,EAAE,kBAAkB,EAAC,MAAM,UAAU,CAAA;AAmBpE,wBAAgB,eAAe,CAC7B,MAAM,GAAE,kBAAuB,GAC9B,kBAAkB,CAyEpB"}
+{"version":3,"file":"useCameraStudio.d.ts","sourceRoot":"","sources":["../src/useCameraStudio.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,kBAAkB,EAAE,kBAAkB,EAAC,MAAM,UAAU,CAAA;AAmBpE,wBAAgB,eAAe,CAC7B,MAAM,GAAE,kBAAuB,GAC9B,kBAAkB,CA0EpB"}

package/dist/useCameraStudio.js

@@ -3,8 +3,8 @@
  *
  * - config 只在首帧取一次(useRef 锁存):后续渲染传新配置不热更,
  *   与 theatre.init 的一次性语义对齐;已 boot 后重挂换 config 不生效
- *   (模块级 promise 复用首 boot),console.warn 点名差异键,换配置需
- *   整页刷新。
+ *   (模块级 promise 复用首 boot),console.warn 点名差异键;换配置需
+ *   整页刷新,或在全部消费者卸载后显式 resetCameraStudio。
  * - 状态机:idle → initializing → ready / error;init 挂 bootstrap 的
  *   共享 promise,StrictMode 双跑/重复触发只复用。
  * - 单页单实例(studio 全局单例):同页第二个实例不占位、直接 error。
@@ -82,5 +82,6 @@ export function useCameraStudio(config = {}) {
         error: phase.error,
         sceneProps,
         api: getCameraStudioApi(),
+        flushState: () => phase.ctx?.flushState() ?? Promise.resolve(),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamerbird/camera-studio",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,6 +12,14 @@
     "./contract-tests": {
       "types": "./dist/assetLibrary/contractTests.d.ts",
       "default": "./dist/assetLibrary/contractTests.js"
+    },
+    "./library-source": {
+      "types": "./dist/assetLibrary/source.d.ts",
+      "default": "./dist/assetLibrary/source.js"
+    },
+    "./poses": {
+      "types": "./dist/poses.d.ts",
+      "default": "./dist/poses.js"
     }
   },
   "files": [