@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/agent/commands/selection.js

@@ -0,0 +1,101 @@
+import { AgentApiError } from '../errors';
+import { resolveSceneSheetObject } from '../objectResolver';
+import { resolveSceneObjectId } from '../runtime/objectRuntime';
+import { requireObject, requireString } from '../validation';
+const emptyInput = { type: 'object', additionalProperties: false };
+const objectIdInput = {
+    type: 'object',
+    properties: {
+        objectId: { type: 'string', description: '带类型场景对象 ID,如 model:Y Bot' },
+    },
+    required: ['objectId'],
+    additionalProperties: false,
+};
+const voidOutput = { type: 'object', additionalProperties: false };
+function noArgs(value) {
+    if (value === undefined || value === null)
+        return {};
+    return requireObject(value);
+}
+function requireStudio(runtime) {
+    const studio = runtime.getStudio();
+    if (!studio) {
+        throw new AgentApiError('SCENE_UNAVAILABLE', 'Studio 不可用');
+    }
+    return studio;
+}
+export function registerSelectionCommands(registry, runtime) {
+    registry.register({
+        name: 'selection.get',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: emptyInput,
+        outputSchema: {
+            type: 'object',
+            properties: {
+                objectIds: { type: 'array', items: { type: 'string' } },
+            },
+            required: ['objectIds'],
+        },
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'SCENE_UNAVAILABLE'],
+        validate: noArgs,
+        execute: async () => {
+            runtime.assertActive();
+            const studio = requireStudio(runtime);
+            const objectIds = [];
+            for (const item of studio.selection) {
+                const id = resolveSceneObjectId(item);
+                if (id)
+                    objectIds.push(id);
+            }
+            return { objectIds };
+        },
+    });
+    registry.register({
+        name: 'selection.selectObject',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: objectIdInput,
+        outputSchema: voidOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: (value) => ({
+            objectId: requireString(requireObject(value), 'objectId'),
+        }),
+        execute: async (args) => {
+            runtime.assertActive();
+            // 先解析(类型/存在性),再要求 Studio 在线
+            const obj = resolveSceneSheetObject(runtime.sheet, args.objectId);
+            const studio = requireStudio(runtime);
+            if (!obj) {
+                throw new AgentApiError('INVALID_STATE', `对象已登记但尚未挂载,无法选择: ${args.objectId}`, { details: { objectId: args.objectId } });
+            }
+            studio.setSelection([obj]);
+        },
+    });
+    registry.register({
+        name: 'selection.clear',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: emptyInput,
+        outputSchema: voidOutput,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'SCENE_UNAVAILABLE'],
+        validate: noArgs,
+        execute: async () => {
+            runtime.assertActive();
+            const studio = requireStudio(runtime);
+            studio.setSelection([]);
+            // 路径控制点选择等会话态一并清理(CameraScene 未绑定时静默跳过)
+            runtime.handlers.clearPathPointSelection?.();
+        },
+    });
+}

package/dist/agent/commands/selection.test.d.ts

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

package/dist/agent/commands/selection.test.d.ts.map

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

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

@@ -0,0 +1,173 @@
+/**
+ * selection.get / selectObject / clear(Task 4):session 域 mutation,
+ * undoable:none。选择解析只认 objectRuntime 里登记的四种业务对象;
+ * 清空同时通知 Scene Runtime 清理路径控制点选择。
+ */
+import { getProject, types as t } from '@dreamerbird/core';
+import { CAMERAS_REGISTRY_KEY } from '../../cameraRegistry';
+import { PLACEMENTS_REGISTRY_KEY } from '../../PlacementManager';
+import { resolveSceneSheetObject } from '../objectResolver';
+import { AgentCommandRegistry } from '../registry';
+import { createAgentRuntime } from '../runtime';
+import { registerSceneSheetObject, unregisterSceneSheetObject, } from '../runtime/objectRuntime';
+import { registerSelectionCommands } from './selection';
+let projectSeq = 0;
+function makeScene({ withStudio = true } = {}) {
+    const project = getProject(`agent-selection-${++projectSeq}`);
+    const sheet = project.sheet('Scene');
+    let selection = [];
+    const setSelection = jest.fn((next) => {
+        selection = [...next];
+    });
+    const studio = {
+        get selection() {
+            return selection;
+        },
+        setSelection,
+    };
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => (withStudio ? studio : undefined),
+        subscribeHistoric: () => () => { },
+    });
+    const registry = new AgentCommandRegistry();
+    registerSelectionCommands(registry, runtime);
+    return {
+        project,
+        sheet,
+        registry,
+        runtime,
+        studio: studio,
+        setSelection,
+    };
+}
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+function seedPlacements(sheet, keys) {
+    const registry = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+    registry.initialValue = {
+        list: JSON.stringify(keys.map((key) => ({ key, position: { x: 0, y: 0, z: 0 } }))),
+    };
+}
+function seedCameras(sheet, cameraKeys) {
+    const registry = sheet.object(CAMERAS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+    registry.initialValue = {
+        list: JSON.stringify(cameraKeys.map((cameraKey) => ({ cameraKey }))),
+    };
+}
+function expectErrorCode(fn, code) {
+    try {
+        fn();
+    }
+    catch (error) {
+        expect(error).toMatchObject({ code });
+        return;
+    }
+    throw new Error(`Expected ${code}`);
+}
+test('selectObject 选中登记的模型 SheetObject', async () => {
+    const { sheet, registry, setSelection, studio } = makeScene();
+    seedPlacements(sheet, ['A']);
+    const objA = { address: { objectKey: 'A' } };
+    registerSceneSheetObject('model:A', objA);
+    try {
+        await registry.execute('selection.selectObject', { objectId: 'model:A' }, ctx());
+        expect(setSelection).toHaveBeenCalledWith([objA]);
+        expect(studio.selection).toEqual([objA]);
+    }
+    finally {
+        unregisterSceneSheetObject('model:A', objA);
+    }
+});
+test('selectObject 不存在的对象返回 OBJECT_NOT_FOUND', async () => {
+    const { registry, setSelection } = makeScene();
+    await expect(registry.execute('selection.selectObject', { objectId: 'model:Missing' }, ctx())).rejects.toMatchObject({
+        code: 'OBJECT_NOT_FOUND',
+        details: { objectId: 'model:Missing', kind: 'model' },
+    });
+    expect(setSelection).not.toHaveBeenCalled();
+});
+test('selectObject 注册表有条目但未挂载返回 INVALID_STATE', async () => {
+    const { sheet, registry, setSelection } = makeScene();
+    seedPlacements(sheet, ['B']);
+    await expect(registry.execute('selection.selectObject', { objectId: 'model:B' }, ctx())).rejects.toMatchObject({
+        code: 'INVALID_STATE',
+        details: { objectId: 'model:B' },
+    });
+    expect(setSelection).not.toHaveBeenCalled();
+});
+test('selectObject 无效 ID 前缀返回 INVALID_ID_KIND', async () => {
+    const { registry } = makeScene();
+    await expect(registry.execute('selection.selectObject', { objectId: 'foo:A' }, ctx())).rejects.toMatchObject({ code: 'INVALID_ID_KIND' });
+});
+test('camera:A 被当作 model 使用返回 INVALID_ID_KIND', () => {
+    const { sheet } = makeScene();
+    expectErrorCode(() => resolveSceneSheetObject(sheet, 'camera:A', 'model'), 'INVALID_ID_KIND');
+});
+test('selection.get 只把能解析为业务对象的选中项返回为 ID', async () => {
+    const { sheet, registry, studio } = makeScene();
+    seedPlacements(sheet, ['A']);
+    seedCameras(sheet, ['Cam 1']);
+    const objA = { address: { objectKey: 'A' } };
+    const objCam = { address: { objectKey: 'Cam 1' } };
+    const unrelated = {
+        address: { objectKey: 'Thingy' },
+    };
+    registerSceneSheetObject('model:A', objA);
+    registerSceneSheetObject('camera:Cam 1', objCam);
+    try {
+        studio.setSelection([objA, unrelated, objCam]);
+        const got = await registry.execute('selection.get', {}, ctx());
+        expect(got).toEqual({ objectIds: ['model:A', 'camera:Cam 1'] });
+    }
+    finally {
+        unregisterSceneSheetObject('model:A', objA);
+        unregisterSceneSheetObject('camera:Cam 1', objCam);
+    }
+});
+test('selection.clear 置空选择并通知 Scene Runtime 清理路径点选择', async () => {
+    const { registry, runtime, setSelection } = makeScene();
+    const clearPathPointSelection = jest.fn();
+    runtime.bindHandlers({ clearPathPointSelection });
+    await registry.execute('selection.clear', {}, ctx());
+    expect(setSelection).toHaveBeenCalledWith([]);
+    expect(clearPathPointSelection).toHaveBeenCalledTimes(1);
+});
+test('Studio 不可用时选择命令返回 SCENE_UNAVAILABLE', async () => {
+    const { registry } = makeScene({ withStudio: false });
+    await expect(registry.execute('selection.get', {}, ctx())).rejects.toMatchObject({
+        code: 'SCENE_UNAVAILABLE',
+    });
+    await expect(registry.execute('selection.clear', {}, ctx())).rejects.toMatchObject({
+        code: 'SCENE_UNAVAILABLE',
+    });
+});
+test('会话销毁后选择命令返回 API_DISPOSED', async () => {
+    const { registry, runtime } = makeScene();
+    runtime.dispose();
+    await expect(registry.execute('selection.clear', {}, ctx())).rejects.toMatchObject({
+        code: 'API_DISPOSED',
+    });
+});
+test('describe() 中选择命令标记 mutation/session、undoable:none', () => {
+    const { registry } = makeScene();
+    const described = registry.describe();
+    const byName = new Map(described.commands.map((c) => [c.name, c]));
+    for (const name of [
+        'selection.get',
+        'selection.selectObject',
+        'selection.clear',
+    ]) {
+        const command = byName.get(name);
+        expect(command).toBeDefined();
+        expect(command).toMatchObject({
+            kind: 'mutation',
+            stateDomain: 'session',
+            undoable: 'none',
+        });
+    }
+});

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

@@ -0,0 +1,25 @@
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+export type SequenceState = {
+    playing: boolean;
+    position: number;
+    length: number;
+};
+/** 播放门面(Task 15 由同名命令转发实现) */
+export type SequenceApi = {
+    getState(): Promise<SequenceState>;
+    play(): Promise<SequenceState>;
+    pause(): Promise<SequenceState>;
+    seek(args: {
+        position: number;
+        snap?: boolean;
+    }): Promise<SequenceState>;
+    setLength(args: {
+        length: number;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+};
+export declare function registerSequenceCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=sequence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/sequence.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAK5C,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,8BAA8B;AAC9B,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;IAClC,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;IAC9B,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;IAC/B,IAAI,CAAC,IAAI,EAAE;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IACtE,SAAS,CAAC,IAAI,EAAE;QACd,MAAM,EAAE,MAAM,CAAA;QACd,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CAChC,CAAA;AA2FD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAmGN"}

package/dist/agent/commands/sequence.js

@@ -0,0 +1,174 @@
+import { val } from '@dreamerbird/dataverse';
+import { AgentApiError } from '../errors';
+import { setSequenceLength } from '../sequenceLength';
+import { requireFiniteNumber, requireObject } from '../validation';
+const emptyInput = { type: 'object', additionalProperties: false };
+const sequenceStateOutput = {
+    type: 'object',
+    properties: {
+        playing: { type: 'boolean' },
+        position: { type: 'number' },
+        length: { type: 'number' },
+    },
+    required: ['playing', 'position', 'length'],
+};
+const revisionOutput = {
+    type: 'object',
+    properties: { revision: { type: 'number' } },
+    required: ['revision'],
+};
+/** 无参命令的运行时校验:允许省略参数或空对象 */
+function noArgs(value) {
+    if (value === undefined || value === null)
+        return {};
+    return requireObject(value);
+}
+/** 从 sequence.pointer 读实时状态,不做缓存 */
+function readSequenceState(sequence) {
+    return {
+        playing: val(sequence.pointer.playing),
+        position: val(sequence.pointer.position),
+        length: val(sequence.pointer.length),
+    };
+}
+const seekInput = {
+    type: 'object',
+    properties: {
+        position: { type: 'number', description: '目标位置(秒)' },
+        snap: {
+            type: 'boolean',
+            description: '先按序列网格吸附再写入,默认 false',
+        },
+    },
+    required: ['position'],
+    additionalProperties: false,
+};
+function validateSeek(value) {
+    const args = requireObject(value);
+    const position = requireFiniteNumber(args.position, 'position');
+    const rawSnap = args.snap;
+    if (rawSnap !== undefined && typeof rawSnap !== 'boolean') {
+        throw new AgentApiError('INVALID_ARGUMENT', 'snap 必须是布尔值');
+    }
+    return { position, snap: rawSnap === true };
+}
+const setLengthInput = {
+    type: 'object',
+    properties: {
+        length: { type: 'number', description: '新的序列时长(秒),必须大于 0' },
+        expectedRevision: {
+            type: 'number',
+            description: '乐观并发:读取场景时的 revision',
+        },
+    },
+    required: ['length'],
+    additionalProperties: false,
+};
+function validateSetLength(value) {
+    const args = requireObject(value);
+    const length = requireFiniteNumber(args.length, 'length');
+    if (length <= 0) {
+        throw new AgentApiError('INVALID_ARGUMENT', 'length 必须大于 0');
+    }
+    let expectedRevision;
+    if (args.expectedRevision !== undefined) {
+        expectedRevision = requireFiniteNumber(args.expectedRevision, 'expectedRevision');
+    }
+    return { length, expectedRevision };
+}
+export function registerSequenceCommands(registry, runtime) {
+    registry.register({
+        name: 'sequence.getState',
+        kind: 'query',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: emptyInput,
+        outputSchema: sequenceStateOutput,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT'],
+        validate: noArgs,
+        execute: async () => {
+            runtime.assertActive();
+            return readSequenceState(runtime.sheet.sequence);
+        },
+    });
+    registry.register({
+        name: 'sequence.play',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: emptyInput,
+        outputSchema: sequenceStateOutput,
+        errorCodes: ['API_DISPOSED'],
+        validate: noArgs,
+        execute: async () => {
+            runtime.assertActive();
+            // core 要求 project.ready 之后才能播放,等待完成后再调用
+            await runtime.project.ready;
+            runtime.assertActive();
+            // 等待 sequence.play() 的返回(播放播完或被中断才 resolve)
+            await runtime.sheet.sequence.play();
+            return readSequenceState(runtime.sheet.sequence);
+        },
+    });
+    registry.register({
+        name: 'sequence.pause',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: emptyInput,
+        outputSchema: sequenceStateOutput,
+        errorCodes: ['API_DISPOSED'],
+        validate: noArgs,
+        execute: async () => {
+            runtime.assertActive();
+            runtime.sheet.sequence.pause();
+            return readSequenceState(runtime.sheet.sequence);
+        },
+    });
+    registry.register({
+        name: 'sequence.seek',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: seekInput,
+        outputSchema: sequenceStateOutput,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT'],
+        validate: validateSeek,
+        execute: async (args) => {
+            runtime.assertActive();
+            const sequence = runtime.sheet.sequence;
+            // core 语义:写 position 前会先 pause、负数/超长会 clamp;
+            // 这里只负责可选吸附并写入,返回读回的实际 position
+            sequence.position = args.snap
+                ? sequence.closestGridPosition(args.position)
+                : args.position;
+            return readSequenceState(sequence);
+        },
+    });
+    registry.register({
+        name: 'sequence.setLength',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: setLengthInput,
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: validateSetLength,
+        execute: async (args) => {
+            runtime.assertActive();
+            // 乐观并发先于事务;length 的 >0/有限校验已在 validate 完成
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            setSequenceLength(runtime.sheet, args.length);
+            // historic 通知 tick 调度:等一个 tick,返回反映本次写入的 revision
+            return { revision: await runtime.nextRevision() };
+        },
+    });
+}

package/dist/agent/commands/sequence.test.d.ts

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

package/dist/agent/commands/sequence.test.d.ts.map

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