@dreamerbird/camera-studio 0.0.0-stage → 0.1.0

package/dist/agent/commands/objects.test.js

@@ -0,0 +1,316 @@
+let projectSeq = 0;
+/** 晚绑定:doMock 工厂只跑一次,getStudioSync 读取当前 setup 的 studio */
+let activeFakeStudio;
+jest.doMock('@dreamerbird/core', () => ({
+    ...jest.requireActual('@dreamerbird/core'),
+    getStudioSync: () => activeFakeStudio,
+}));
+const cleanups = [];
+afterEach(() => {
+    while (cleanups.length)
+        cleanups.pop()();
+});
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+function setup(options = {}) {
+    const { getPointerParts } = require('@dreamerbird/dataverse');
+    const setCalls = [];
+    const fakeStudio = {
+        transaction: jest.fn((fn) => fn({
+            set: (pointer, value) => {
+                if (options.throwInTransaction)
+                    throw new Error('boom');
+                const { path } = getPointerParts(pointer);
+                setCalls.push({ path: path.join('.'), value });
+            },
+        })),
+    };
+    activeFakeStudio = fakeStudio;
+    cleanups.push(() => {
+        activeFakeStudio = undefined;
+    });
+    const core = require('@dreamerbird/core');
+    const { globals } = require('@dreamerbird/core/globals');
+    const { AgentCommandRegistry } = require('../registry');
+    const { createAgentRuntime } = require('../runtime');
+    const objectRuntime = require('../runtime/objectRuntime');
+    const { registerObjectCommands } = require('./objects');
+    const { PLACEMENTS_REGISTRY_KEY } = require('../../PlacementManager');
+    const state = options.tracks
+        ? stateWithTracks(globals.currentProjectStateDefinitionVersion, options.tracks.trackIdByPropPath, options.tracks.keyframeValue)
+        : undefined;
+    const project = core.getProject(`agent-objects-${++projectSeq}`, state ? { state: state } : {});
+    const sheet = project.sheet('Scene');
+    let notifyHistoric = () => { };
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => fakeStudio,
+        subscribeHistoric: (listener) => {
+            notifyHistoric = listener;
+            return () => { };
+        },
+    });
+    const registry = new AgentCommandRegistry();
+    registerObjectCommands(registry, runtime);
+    /** 登记后的清理(模块级登记表跨用例存活,必须逐用例清) */
+    function registerMounted(id, obj) {
+        objectRuntime.registerSceneSheetObject(id, obj);
+        cleanups.push(() => objectRuntime.unregisterSceneSheetObject(id, obj));
+    }
+    /** 布景:注册表写 'Foo' 条目并把 SheetObject 登记为 model:Foo */
+    function mountFoo() {
+        const t = core.types;
+        const registryObj = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+        registryObj.initialValue = {
+            list: JSON.stringify([{ key: 'Foo', position: { x: 0, y: 0, z: 0 } }]),
+        };
+        const obj = sheet.object('Foo', {
+            position: t.compound({
+                x: t.number(0),
+                y: t.number(0),
+                z: t.number(0),
+            }),
+            label: t.string('hello'),
+            visible: t.boolean(true),
+        });
+        registerMounted('model:Foo', obj);
+        return obj;
+    }
+    return {
+        core,
+        sheet,
+        registry,
+        runtime,
+        fakeStudio,
+        setCalls,
+        mountFoo,
+        notifyHistoric: () => notifyHistoric(),
+        objectRuntime,
+        PLACEMENTS_REGISTRY_KEY,
+    };
+}
+/** 带轨道的初始 project state(与 theatre 存档同构) */
+function stateWithTracks(definitionVersion, trackIdByPropPath, keyframeValue) {
+    const trackData = {};
+    for (const trackId of Object.values(trackIdByPropPath)) {
+        trackData[trackId] = {
+            type: 'BasicKeyframedTrack',
+            keyframes: {
+                byId: {
+                    kf1: {
+                        id: 'kf1',
+                        position: 0,
+                        connectedRight: true,
+                        handles: [0.5, 0.5, 0.5, 0.5],
+                        value: keyframeValue,
+                    },
+                },
+                allIds: { kf1: true },
+            },
+        };
+    }
+    return {
+        definitionVersion,
+        sheetsById: {
+            Scene: {
+                staticOverrides: { byObject: {} },
+                sequence: {
+                    type: 'PositionalSequence',
+                    length: 10,
+                    subUnitsPerUnit: 30,
+                    tracksByObject: { Foo: { trackIdByPropPath, trackData } },
+                },
+            },
+        },
+    };
+}
+describe('objects.update 静态更新', () => {
+    test('合法 position 一次性更新:单事务写完整个 patch,返回当前 revision', async () => {
+        const { registry, fakeStudio, setCalls, mountFoo } = setup();
+        mountFoo();
+        const result = await registry.execute('objects.update', {
+            objectId: 'model:Foo',
+            props: { position: { x: 1, y: 2, z: 3 }, visible: false },
+        }, ctx());
+        expect(result).toEqual({ revision: 1 });
+        expect(fakeStudio.transaction).toHaveBeenCalledTimes(1);
+        expect(setCalls).toEqual([
+            { path: 'position', value: { x: 1, y: 2, z: 3 } },
+            { path: 'visible', value: false },
+        ]);
+    });
+    test('未知属性返回 INVALID_ARGUMENT,不进入事务', async () => {
+        const { registry, fakeStudio, mountFoo } = setup();
+        mountFoo();
+        await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { nope: 1 } }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('compound 不完整(只传 position.x)返回 INVALID_ARGUMENT', async () => {
+        const { registry, fakeStudio, mountFoo } = setup();
+        mountFoo();
+        await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { position: { x: 1 } } }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('compound 多余键返回 INVALID_ARGUMENT', async () => {
+        const { registry, fakeStudio, mountFoo } = setup();
+        mountFoo();
+        await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { position: { x: 1, y: 2, z: 3, w: 4 } } }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('NaN 与 Infinity 被拒绝', async () => {
+        const { registry, fakeStudio, mountFoo } = setup();
+        mountFoo();
+        for (const bad of [NaN, Infinity, -Infinity]) {
+            await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { position: { x: bad, y: 0, z: 0 } } }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        }
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('运行时类型不匹配(字符串写给 number)返回 INVALID_ARGUMENT', async () => {
+        const { registry, fakeStudio, mountFoo } = setup();
+        mountFoo();
+        await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { position: { x: 'a', y: 0, z: 0 } } }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { visible: 'yes' } }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('领域专用属性被 objects.update 拒绝(INVALID_ARGUMENT)', async () => {
+        const { registry, fakeStudio, mountFoo } = setup();
+        mountFoo();
+        const owned = [
+            'points',
+            'pose',
+            'poseOverride',
+            'gestureL',
+            'gestureR',
+            'animation',
+            'aimTarget',
+            'pathKey',
+            'parent',
+            'source',
+        ];
+        for (const prop of owned) {
+            await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { [prop]: 'x' } }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        }
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('注册表有条目但未挂载:INVALID_STATE', async () => {
+        const { core, sheet, registry, fakeStudio, PLACEMENTS_REGISTRY_KEY } = setup();
+        const registryObj = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: core.types.string('[]') }, { hideFromOutline: true });
+        registryObj.initialValue = {
+            list: JSON.stringify([{ key: 'Ghost', position: { x: 0, y: 0, z: 0 } }]),
+        };
+        await expect(registry.execute('objects.update', { objectId: 'model:Ghost', props: { label: 'x' } }, ctx())).rejects.toMatchObject({ code: 'INVALID_STATE' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('不存在的对象:OBJECT_NOT_FOUND', async () => {
+        const { registry } = setup();
+        await expect(registry.execute('objects.update', { objectId: 'model:Nope', props: { label: 'x' } }, ctx())).rejects.toMatchObject({ code: 'OBJECT_NOT_FOUND' });
+    });
+});
+describe('objects.update 建轨保护', () => {
+    test('compound 任一叶子已建轨:整个更新在事务前返回 INVALID_STATE', async () => {
+        const { registry, fakeStudio, mountFoo } = setup({
+            tracks: {
+                trackIdByPropPath: { '["position","x"]': 'track-x' },
+                keyframeValue: 5,
+            },
+        });
+        mountFoo();
+        await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { position: { x: 1, y: 2, z: 3 } } }, ctx())).rejects.toMatchObject({ code: 'INVALID_STATE' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+    test('简单属性已建轨:INVALID_STATE,同事务其他属性也不写', async () => {
+        const { registry, fakeStudio, mountFoo } = setup({
+            tracks: {
+                trackIdByPropPath: { '["label"]': 'track-label' },
+                keyframeValue: 'a',
+            },
+        });
+        mountFoo();
+        await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { visible: false, label: 'b' } }, ctx())).rejects.toMatchObject({ code: 'INVALID_STATE' });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+    });
+});
+describe('objects.update revision 与事务', () => {
+    test('historic 通知后 expectedRevision 过期:REVISION_CONFLICT,没有任何 set', async () => {
+        const { registry, runtime, fakeStudio, setCalls, mountFoo, notifyHistoric } = setup();
+        mountFoo();
+        notifyHistoric();
+        expect(runtime.revision).toBe(2);
+        await expect(registry.execute('objects.update', {
+            objectId: 'model:Foo',
+            props: { position: { x: 1, y: 2, z: 3 } },
+            expectedRevision: 1,
+        }, ctx())).rejects.toMatchObject({
+            code: 'REVISION_CONFLICT',
+            details: { expectedRevision: 1, actualRevision: 2 },
+        });
+        expect(fakeStudio.transaction).not.toHaveBeenCalled();
+        expect(setCalls).toEqual([]);
+    });
+    test('expectedRevision 匹配当前 revision 时正常执行', async () => {
+        const { registry, setCalls, mountFoo } = setup();
+        mountFoo();
+        const result = await registry.execute('objects.update', { objectId: 'model:Foo', props: { label: 'renamed' }, expectedRevision: 1 }, ctx());
+        expect(result).toEqual({ revision: 1 });
+        expect(setCalls).toEqual([{ path: 'label', value: 'renamed' }]);
+    });
+    test('事务回调抛错:命令失败且 revision 不增加', async () => {
+        const { registry, runtime, mountFoo } = setup({ throwInTransaction: true });
+        mountFoo();
+        await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { label: 'x' } }, ctx())).rejects.toMatchObject({ code: 'INTERNAL_ERROR' });
+        // revision 只随真实 historic 通知递增,不由命令手工加一
+        expect(runtime.revision).toBe(1);
+    });
+    test('会话销毁后更新返回 API_DISPOSED', async () => {
+        const { registry, runtime, mountFoo } = setup();
+        mountFoo();
+        runtime.dispose();
+        await expect(registry.execute('objects.update', { objectId: 'model:Foo', props: { label: 'x' } }, ctx())).rejects.toMatchObject({ code: 'API_DISPOSED' });
+    });
+    test('describe() 元数据:mutation/project/single-step 且接受 expectedRevision', () => {
+        const { registry } = setup();
+        const command = registry
+            .describe()
+            .commands.find((c) => c.name === 'objects.update');
+        expect(command).toBeDefined();
+        expect(command).toMatchObject({
+            kind: 'mutation',
+            stateDomain: 'project',
+            undoable: 'single-step',
+            completion: 'committed',
+            acceptsExpectedRevision: true,
+        });
+    });
+});
+describe('propAccess 建轨检测(Task 7 前置)', () => {
+    test('isPropSequenced:顶层 compound/叶子路径/未建轨三分支', () => {
+        const { mountFoo, objectRuntime } = setup({
+            tracks: {
+                trackIdByPropPath: { '["position","x"]': 'track-x' },
+                keyframeValue: 5,
+            },
+        });
+        mountFoo();
+        const { isPropSequenced } = require('../propAccess');
+        const obj = objectRuntime.getSceneSheetObject('model:Foo');
+        expect(isPropSequenced(obj, 'position')).toBe(true);
+        expect(isPropSequenced(obj, 'position.x')).toBe(true);
+        expect(isPropSequenced(obj, 'position.y')).toBe(false);
+        expect(isPropSequenced(obj, 'visible')).toBe(false);
+        expect(isPropSequenced(obj, 'label')).toBe(false);
+    });
+    test('getSimplePropPointer 按点路径导航到叶子指针', () => {
+        const { mountFoo, objectRuntime } = setup();
+        mountFoo();
+        const { getSimplePropPointer } = require('../propAccess');
+        const { getPointerParts } = require('@dreamerbird/dataverse');
+        const obj = objectRuntime.getSceneSheetObject('model:Foo');
+        const pointer = getSimplePropPointer(obj, 'position.x');
+        expect(getPointerParts(pointer).path).toEqual(['position', 'x']);
+    });
+});
+export {};

package/dist/agent/commands/paths.d.ts

@@ -0,0 +1,111 @@
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+import type { SceneObjectId, Vec3 } from '../types';
+declare module '../runtime' {
+    interface AgentSceneRuntimeHandlers {
+        /**
+         * 进入路径编辑模式(CameraScene 绑定,转发 enterPathEdit:置编辑态
+         * 并清掉 theatre 对象选中,两套 gizmo 不同时出现);pathKey 的存在性
+         * 由命令侧先校验。
+         */
+        startPathEditing(args: {
+            pathKey: string;
+        }): void;
+        /**
+         * 退出路径编辑模式(CameraScene 绑定,失焦式退出:清编辑态,
+         * 不回头重选路径本体)。
+         */
+        exitPathEditing(): void;
+        /**
+         * 选中路径控制点(CameraScene 绑定);路径正在编辑与点存在性
+         * 由命令侧先校验。
+         */
+        selectPathPoint(args: {
+            pathKey: string;
+            pointKey: string;
+        }): void;
+        /**
+         * 当前路径编辑会话状态(selectPoint 的"路径正在编辑"校验用);
+         * 未编辑时 pathKey 为 null。
+         */
+        getPathEditingState(): {
+            pathKey: string | null;
+            pointKey: string | null;
+        };
+    }
+}
+/** 预设条目 DTO(listPresets 输出;与 PathPreset 同形状的可序列化子集) */
+export type PathPresetInfo = {
+    id: string;
+    name: string;
+    en: string;
+    closed: boolean;
+    durSeconds: number;
+};
+/** 路径门面(Task 15 由同名命令转发实现) */
+export type PathsApi = {
+    listPresets(): Promise<PathPresetInfo[]>;
+    createPreset(args: {
+        preset: string;
+        at?: Vec3;
+        expectedRevision?: number;
+    }): Promise<{
+        pathId: SceneObjectId;
+        pointKeys: string[];
+        revision: number;
+    }>;
+    addPoint(args: {
+        pathId: SceneObjectId;
+        expectedRevision?: number;
+    }): Promise<{
+        pointKey: string;
+        revision: number;
+    }>;
+    updatePoint(args: {
+        pathId: SceneObjectId;
+        pointKey: string;
+        position?: Vec3;
+        handles?: {
+            side: 'left' | 'right';
+            offset: Vec3;
+        };
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    deletePoint(args: {
+        pathId: SceneObjectId;
+        pointKey: string;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+        pathDeleted: boolean;
+    }>;
+    setPointTiming(args: {
+        pathId: SceneObjectId;
+        pointKey: string;
+        u: number | null;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    sample(args: {
+        pathId: SceneObjectId;
+        u: number;
+    }): Promise<{
+        position: Vec3;
+    }>;
+};
+/** 路径编辑会话门面(Task 15 由同名命令转发实现) */
+export type PathsSessionApi = {
+    startEditing(args: {
+        pathId: SceneObjectId;
+    }): Promise<void>;
+    exitEditing(): Promise<void>;
+    selectPoint(args: {
+        pathId: SceneObjectId;
+        pointKey: string;
+    }): Promise<void>;
+};
+export declare function registerPathCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=paths.d.ts.map

package/dist/agent/commands/paths.d.ts.map

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