@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,268 @@
+/**
+ * models.create(2026-10-17,Task 8):从模型资产直接创建到指定位置。
+ *
+ * Scene Runtime 的 createModel handler 用假实现(返回 key + deferred
+ * persisted,形状与接线后的 placeLibraryEntryAt 一致);挂载完成由测试
+ * 手动模拟:注册表写条目 + objectRuntime 登记 SheetObject,然后 resolve
+ * persisted。命令 promise 在 persisted settle 前必须保持 pending;资产
+ * 缺失 / 资产类型不符 / 挂载失败 / 挂载期间 dispose 分别映射
+ * ASSET_NOT_FOUND / INVALID_ARGUMENT / RESOURCE_LOAD_FAILED /
+ * API_DISPOSED,任何失败路径都不得返回成功。
+ */
+import { getProject, types as t } from '@dreamerbird/core';
+import { globals } from '@dreamerbird/core/globals';
+import { PLACEMENTS_REGISTRY_KEY } from '../../PlacementManager';
+import { formatSceneObjectId } from '../objectIds';
+import { AgentCommandRegistry } from '../registry';
+import { createAgentRuntime } from '../runtime';
+import { registerSceneSheetObject, unregisterSceneSheetObject, } from '../runtime/objectRuntime';
+import { registerModelCommands } from './models';
+let projectSeq = 0;
+const cleanups = [];
+afterEach(() => {
+    while (cleanups.length)
+        cleanups.pop()();
+});
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+/** 真实 macrotask 冲刷:project.ready 经 setTimeout(0) 兑现 */
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+const modelEntry = {
+    id: 'asset-1',
+    kind: 'model',
+    name: 'Y Bot',
+    rig: 'mixamo',
+    blobId: 'blob-1',
+    contentHash: 'hash-1',
+    boneCount: 65,
+    vertexCount: 1000,
+    createdAt: 1,
+};
+const POSITION = { x: 1, y: 0, z: -2 };
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+function setup() {
+    // config.state 必须提供:无 state 且无 window 时 project.ready 永不兑现
+    const project = getProject(`agent-models-${++projectSeq}`, {
+        state: {
+            definitionVersion: globals.currentProjectStateDefinitionVersion,
+            sheetsById: {
+                Scene: {
+                    staticOverrides: { byObject: {} },
+                    sequence: {
+                        type: 'PositionalSequence',
+                        length: 10,
+                        subUnitsPerUnit: 30,
+                        tracksByObject: {},
+                    },
+                },
+            },
+        },
+    });
+    const sheet = project.sheet('Scene');
+    const library = {
+        getEntry: jest.fn(async (id) => id === modelEntry.id ? modelEntry : undefined),
+    };
+    let notifyHistoric = () => { };
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: library,
+        getStudio: () => undefined,
+        subscribeHistoric: (listener) => {
+            notifyHistoric = listener;
+            return () => { };
+        },
+    });
+    const registry = new AgentCommandRegistry();
+    registerModelCommands(registry, runtime);
+    const createModel = jest.fn();
+    return {
+        project,
+        sheet,
+        runtime,
+        registry,
+        library,
+        createModel,
+        notifyHistoric: () => notifyHistoric(),
+    };
+}
+/** 绑定假 createModel handler,返回 {key, persisted} 句柄 */
+function bindCreateModel(runtime, createModel, key, persisted) {
+    createModel.mockReturnValue({ key, persisted });
+    const unbind = runtime.bindHandlers({
+        createModel: (args) => createModel(args),
+    });
+    cleanups.push(unbind);
+}
+/** 模拟挂载完成:注册表写条目 + objectRuntime 登记 SheetObject */
+function mountModel(sheet, key) {
+    const registryObj = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+    registryObj.initialValue = {
+        list: JSON.stringify([
+            { key, libraryEntryId: modelEntry.id, position: POSITION },
+        ]),
+    };
+    const obj = sheet.object(key, {
+        position: t.compound({ x: t.number(1), y: t.number(0), z: t.number(-2) }),
+    });
+    const id = formatSceneObjectId('model', key);
+    registerSceneSheetObject(id, obj);
+    cleanups.push(() => unregisterSceneSheetObject(id, obj));
+    return obj;
+}
+/** 等命令推进到 createModel 已调用(即已 parked 在 persisted 上) */
+async function untilCreateModelCalled(createModel) {
+    for (let i = 0; i < 50 && createModel.mock.calls.length === 0; i++) {
+        await tick();
+    }
+    expect(createModel).toHaveBeenCalled();
+}
+describe('models.create 注册与元数据', () => {
+    test('注册为项目单步 mutation,completion:mounted,接受 expectedRevision', () => {
+        const { registry } = setup();
+        expect(registry.has('models.create')).toBe(true);
+        const described = new Map(registry.describe().commands.map((c) => [c.name, c]));
+        expect(described.get('models.create')).toMatchObject({
+            kind: 'mutation',
+            stateDomain: 'project',
+            undoable: 'single-step',
+            completion: 'mounted',
+            acceptsExpectedRevision: true,
+        });
+    });
+});
+describe('models.create 完成语义', () => {
+    test('persisted resolve 前保持 pending;挂载完成后返回 model:<key> 与当前 revision', async () => {
+        const { registry, sheet, runtime, createModel, notifyHistoric } = setup();
+        const mount = deferred();
+        bindCreateModel(runtime, createModel, 'Y Bot', mount.promise);
+        let resolved = false;
+        const promise = registry
+            .execute('models.create', { assetId: modelEntry.id, position: POSITION }, ctx())
+            .then((result) => {
+            resolved = true;
+            return result;
+        });
+        await untilCreateModelCalled(createModel);
+        // handler 收到的就是库真实条目与命令位置
+        expect(createModel).toHaveBeenCalledWith({
+            entry: modelEntry,
+            position: POSITION,
+        });
+        await tick();
+        // persisted 未 settle:命令必须保持 pending
+        expect(resolved).toBe(false);
+        // 模拟挂载:注册表条目 + SheetObject 登记,然后 persisted 兑现;
+        // notifyHistoric 模拟 scrub.commit 的 historic 通知(revision 递增)
+        mountModel(sheet, 'Y Bot');
+        notifyHistoric();
+        mount.resolve();
+        await expect(promise).resolves.toEqual({
+            objectId: 'model:Y Bot',
+            revision: 2,
+        });
+    });
+    test('资产不存在 → ASSET_NOT_FOUND(details 含 assetId),不调用 handler', async () => {
+        const { registry, createModel } = setup();
+        await expect(registry.execute('models.create', { assetId: 'missing', position: POSITION }, ctx())).rejects.toMatchObject({
+            code: 'ASSET_NOT_FOUND',
+            details: { assetId: 'missing' },
+        });
+        expect(createModel).not.toHaveBeenCalled();
+    });
+    test('资产 kind 不是 model → INVALID_ARGUMENT,不调用 handler', async () => {
+        const { registry, library, runtime, createModel } = setup();
+        library.getEntry.mockResolvedValueOnce({
+            id: 'asset-1',
+            kind: 'pose',
+            name: 'Pose',
+            rig: 'mixamo',
+            bones: {},
+            createdAt: 1,
+        });
+        const mount = deferred();
+        bindCreateModel(runtime, createModel, 'Y Bot', mount.promise);
+        await expect(registry.execute('models.create', { assetId: modelEntry.id, position: POSITION }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        expect(createModel).not.toHaveBeenCalled();
+    });
+    test('Scene Runtime 未绑定 createModel → SCENE_UNAVAILABLE', async () => {
+        const { registry } = setup();
+        await expect(registry.execute('models.create', { assetId: modelEntry.id, position: POSITION }, ctx())).rejects.toMatchObject({ code: 'SCENE_UNAVAILABLE' });
+    });
+    test('挂载失败(persisted reject)→ RESOURCE_LOAD_FAILED,不返回成功', async () => {
+        const { registry, runtime, createModel } = setup();
+        const mount = deferred();
+        bindCreateModel(runtime, createModel, 'Y Bot', mount.promise);
+        const promise = registry.execute('models.create', { assetId: modelEntry.id, position: POSITION }, ctx());
+        await untilCreateModelCalled(createModel);
+        mount.reject(new Error('GLTF 解析失败'));
+        await expect(promise).rejects.toMatchObject({
+            code: 'RESOURCE_LOAD_FAILED',
+            details: { assetId: modelEntry.id, cause: 'GLTF 解析失败' },
+        });
+    });
+    test('挂载期间 API dispose → API_DISPOSED,不返回成功', async () => {
+        const { registry, runtime, createModel } = setup();
+        const mount = deferred();
+        bindCreateModel(runtime, createModel, 'Y Bot', mount.promise);
+        const promise = registry.execute('models.create', { assetId: modelEntry.id, position: POSITION }, ctx());
+        await untilCreateModelCalled(createModel);
+        runtime.dispose();
+        // dispose 后挂载链路以失败收场(生产:场景卸载 reject waiter);
+        // 命令必须把 dispose 语义置于挂载失败之上
+        mount.reject(new Error('组件已卸载'));
+        await expect(promise).rejects.toMatchObject({ code: 'API_DISPOSED' });
+    });
+    test('persisted 已兑现但 SheetObject 未登记 → INTERNAL_ERROR(不静默成功)', async () => {
+        const { registry, sheet, runtime, createModel } = setup();
+        const mount = deferred();
+        bindCreateModel(runtime, createModel, 'Y Bot', mount.promise);
+        const promise = registry.execute('models.create', { assetId: modelEntry.id, position: POSITION }, ctx());
+        await untilCreateModelCalled(createModel);
+        // 只写注册表条目,不登记运行时 SheetObject —— resolver 报 mounted:false
+        const registryObj = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+        registryObj.initialValue = {
+            list: JSON.stringify([
+                { key: 'Y Bot', libraryEntryId: modelEntry.id, position: POSITION },
+            ]),
+        };
+        mount.resolve();
+        await expect(promise).rejects.toMatchObject({ code: 'INTERNAL_ERROR' });
+    });
+    test('expectedRevision 冲突 → REVISION_CONFLICT,不调用 handler', async () => {
+        const { registry, runtime, createModel, notifyHistoric } = setup();
+        const mount = deferred();
+        bindCreateModel(runtime, createModel, 'Y Bot', mount.promise);
+        notifyHistoric();
+        await expect(registry.execute('models.create', { assetId: modelEntry.id, position: POSITION, expectedRevision: 1 }, ctx())).rejects.toMatchObject({
+            code: 'REVISION_CONFLICT',
+            details: { expectedRevision: 1, actualRevision: 2 },
+        });
+        expect(createModel).not.toHaveBeenCalled();
+    });
+    test('参数校验:缺 assetId / 坏 position / 坏 expectedRevision → INVALID_ARGUMENT', async () => {
+        const { registry } = setup();
+        await expect(registry.execute('models.create', { position: POSITION }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        await expect(registry.execute('models.create', { assetId: modelEntry.id, position: { x: 1, y: 0 } }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        await expect(registry.execute('models.create', {
+            assetId: modelEntry.id,
+            position: POSITION,
+            expectedRevision: 'one',
+        }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    });
+    test('会话销毁后调用 → API_DISPOSED', async () => {
+        const { registry, runtime } = setup();
+        runtime.dispose();
+        await expect(registry.execute('models.create', { assetId: modelEntry.id, position: POSITION }, ctx())).rejects.toMatchObject({ code: 'API_DISPOSED' });
+    });
+});

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

@@ -0,0 +1,4 @@
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+export declare function registerObjectCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=objects.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"objects.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/objects.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AA0F5C,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAyGN"}

package/dist/agent/commands/objects.js

@@ -0,0 +1,182 @@
+/**
+ * objects 命令(2026-10-17,Task 5;2026-10-19,Task 14 补 delete):
+ * 通用静态属性更新与 revision 冲突保护 + 统一对象删除。
+ *
+ * update 执行顺序(spec 9.1 + Task 5 约束):参数校验 → 对象存在/挂载 →
+ * 领域专用属性拒绝 → 值形状与建轨校验(propAccess,全部在事务之前) →
+ * expectedRevision 乐观并发 → 单个 studio.transaction 写完整个 patch。
+ * 返回当前 historic 驱动的 revision,不手工加一。
+ *
+ * delete 执行顺序(spec 9.2):参数校验 → 带类型 ID 解析与注册表存在性
+ * (只探测不创建)→ Studio 可用性 → expectedRevision(先于任何副作用)
+ * → 按类型的领域删除(deleteSceneObject,forgetObject/注册表/绑定回退
+ * 合并为单个事务 = 一步撤销)→ 会话清理(选择里摘除被删对象 +
+ * afterSceneObjectDeleted handler)。领域校验失败时不调用会话清理、
+ * 不返回 deleted。
+ */
+import { AgentApiError } from '../errors';
+import { deleteSceneObject } from '../deleteHandlers';
+import { resolveSceneSheetObject } from '../objectResolver';
+import { assertStaticPropsWritable, domainOwnedProps, setStaticProps, } from '../propAccess';
+import { getSceneSheetObject } from '../runtime/objectRuntime';
+import { requireFiniteNumber, requireObject, requireString } from '../validation';
+const updateInput = {
+    type: 'object',
+    properties: {
+        objectId: { type: 'string', description: '带类型场景对象 ID,如 model:Y Bot' },
+        props: {
+            type: 'object',
+            description: '顶层静态属性 patch;compound 属性必须提供完整值',
+        },
+        expectedRevision: {
+            type: 'number',
+            description: '乐观并发:读取场景时的 revision',
+        },
+    },
+    required: ['objectId', 'props'],
+    additionalProperties: false,
+};
+const revisionOutput = {
+    type: 'object',
+    properties: { revision: { type: 'number' } },
+    required: ['revision'],
+};
+const deleteInput = {
+    type: 'object',
+    properties: {
+        objectId: {
+            type: 'string',
+            description: '带类型场景对象 ID(model:/camera:/anchor:/path:<key>);类型决定完整清理行为(spec 9.2)',
+        },
+        expectedRevision: {
+            type: 'number',
+            description: '乐观并发:读取场景时的 revision',
+        },
+    },
+    required: ['objectId'],
+    additionalProperties: false,
+};
+function validateDelete(value) {
+    const args = requireObject(value);
+    return {
+        objectId: requireString(args, 'objectId'),
+        expectedRevision: args.expectedRevision === undefined
+            ? undefined
+            : requireFiniteNumber(args.expectedRevision, 'expectedRevision'),
+    };
+}
+function validateUpdate(value) {
+    const args = requireObject(value);
+    const objectId = requireString(args, 'objectId');
+    const rawProps = args.props;
+    if (!rawProps ||
+        typeof rawProps !== 'object' ||
+        Array.isArray(rawProps) ||
+        Object.keys(rawProps).length === 0) {
+        throw new AgentApiError('INVALID_ARGUMENT', 'props 必须是非空对象');
+    }
+    let expectedRevision;
+    if (args.expectedRevision !== undefined) {
+        expectedRevision = requireFiniteNumber(args.expectedRevision, 'expectedRevision');
+    }
+    return {
+        objectId,
+        props: rawProps,
+        expectedRevision,
+    };
+}
+export function registerObjectCommands(registry, runtime) {
+    registry.register({
+        name: 'objects.update',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: updateInput,
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'INVALID_STATE',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: validateUpdate,
+        execute: async (args) => {
+            runtime.assertActive();
+            const sheetObject = resolveSceneSheetObject(runtime.sheet, args.objectId);
+            if (!sheetObject) {
+                throw new AgentApiError('INVALID_STATE', `对象未挂载,无法更新: ${args.objectId}`, { details: { objectId: args.objectId } });
+            }
+            // 专用属性由领域命令自校验后经 setStaticProps 写;通用入口拒绝
+            for (const key of Object.keys(args.props)) {
+                if (domainOwnedProps.has(key)) {
+                    throw new AgentApiError('INVALID_ARGUMENT', `属性 ${key} 由领域命令管理,objects.update 不可写`, { details: { prop: key } });
+                }
+            }
+            // 全部值与建轨状态校验先于事务;setStaticProps 内部会再校验一次
+            // (领域命令直接调用它时同样需要这道 guard)
+            assertStaticPropsWritable(sheetObject, args.props);
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            setStaticProps(sheetObject, args.props);
+            // historic 通知 tick 调度:等一个 tick,返回反映本次写入的 revision
+            return { revision: await runtime.nextRevision() };
+        },
+    });
+    registry.register({
+        name: 'objects.delete',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'single-step',
+        completion: 'committed',
+        inputSchema: deleteInput,
+        outputSchema: {
+            type: 'object',
+            properties: {
+                deleted: { type: 'string', description: '已删除的带类型场景对象 ID' },
+                revision: { type: 'number' },
+            },
+            required: ['deleted', 'revision'],
+        },
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: validateDelete,
+        execute: async (args) => {
+            runtime.assertActive();
+            // 领域删除:类型/存在性/Studio 可用性校验 → expectedRevision
+            // (先于任何副作用)→ 单个项目事务(一步撤销)。校验失败抛出,
+            // 不调用会话清理、不返回 deleted
+            const deleted = deleteSceneObject(runtime, args.objectId, () => {
+                if (args.expectedRevision !== undefined) {
+                    runtime.assertRevision(args.expectedRevision);
+                }
+            });
+            // 会话清理(项目事务已提交,同步执行不跨 await):
+            // 1) 把被删对象摘出 studio 选择——注册表行已删但组件尚未卸载的
+            //    窗口里,selection.get 不得返回已失效 ID(Task 4 遗留窗口在
+            //    此关闭:注册表移除与选择清理在同一调用栈完成,命令间无交叉);
+            // 2) CameraScene 侧会话态(路径编辑/点选择/大纲伪集合)经
+            //    afterSceneObjectDeleted handler 清理(未绑定静默跳过)
+            const studio = runtime.getStudio();
+            const mounted = getSceneSheetObject(deleted.id);
+            if (studio && mounted) {
+                const selection = studio.selection;
+                if (selection.includes(mounted)) {
+                    studio.setSelection(selection.filter((item) => item !== mounted));
+                }
+            }
+            runtime.handlers.afterSceneObjectDeleted?.(deleted);
+            return { deleted: deleted.id, revision: await runtime.nextRevision() };
+        },
+    });
+}

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

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

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

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