@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,12 @@
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+/** 项目门面(Task 15 由同名命令转发实现) */
+export type ProjectApi = {
+    /** 导出 Theatre 项目存档(深拷贝;不含资产与会话状态) */
+    exportState(): Promise<{
+        projectId: string;
+        content: unknown;
+    }>;
+};
+export declare function registerProjectCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=project.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/project.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAI5C,8BAA8B;AAC9B,MAAM,MAAM,UAAU,GAAG;IACvB,qCAAqC;IACrC,WAAW,IAAI,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAC,CAAC,CAAA;CAC9D,CAAA;AAqBD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAyBN"}

package/dist/agent/commands/project.js

@@ -0,0 +1,42 @@
+import { AgentApiError } from '../errors';
+import { requireObject } from '../validation';
+const emptyInput = { type: 'object', additionalProperties: false };
+const exportStateOutput = {
+    type: 'object',
+    properties: {
+        projectId: { type: 'string' },
+        content: { type: 'object', description: 'Theatre 项目存档(深拷贝)' },
+    },
+    required: ['projectId', 'content'],
+};
+function requireInitializedStudio(runtime) {
+    const studio = runtime.getStudio();
+    if (!studio) {
+        throw new AgentApiError('API_NOT_READY', 'Studio 未初始化,无法导出项目状态');
+    }
+    return studio;
+}
+export function registerProjectCommands(registry, runtime) {
+    registry.register({
+        name: 'project.exportState',
+        kind: 'query',
+        stateDomain: 'project',
+        undoable: 'none',
+        inputSchema: emptyInput,
+        outputSchema: exportStateOutput,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'API_NOT_READY'],
+        validate: (value) => {
+            if (value === undefined || value === null)
+                return {};
+            return requireObject(value);
+        },
+        execute: async () => {
+            runtime.assertActive();
+            const studio = requireInitializedStudio(runtime);
+            const projectId = runtime.project.address.projectId;
+            const content = studio.createContentOfSaveFile(projectId);
+            // 深拷贝:返回值必须与 studio 持有的存档对象完全脱钩
+            return { projectId, content: JSON.parse(JSON.stringify(content)) };
+        },
+    });
+}

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

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

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

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

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

@@ -0,0 +1,125 @@
+/**
+ * project 命令(2026-10-17,Task 12):project.exportState。
+ *
+ * query/project、undoable:none:调用 studio.createContentOfSaveFile(
+ * project.address.projectId) 导出 Theatre 项目存档,返回深拷贝——
+ * 调用方改返回值不得污染 studio 内部状态。存档只表示 Theatre 项目
+ * 状态:不含 Library 资产条目、活动相机、PIP 等会话态(spec 9.3),
+ * 这些字段也绝不会出现在返回结构上。Studio 未初始化返回
+ * API_NOT_READY(不静默成功)。
+ *
+ * 布景同 selection.test.ts:真实 core project + 注入式假 studio,
+ * node 环境。
+ */
+import { getProject } from '@dreamerbird/core';
+import { AgentCommandRegistry } from '../registry';
+import { createAgentRuntime } from '../runtime';
+import { registerProjectCommands } from './project';
+let projectSeq = 0;
+const cleanups = [];
+afterEach(() => {
+    while (cleanups.length)
+        cleanups.pop()();
+});
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+/** 假存档内容:嵌套结构,验证深拷贝与调用参数 */
+function fakeSaveFileContent() {
+    return {
+        definitionVersion: '2026.10.17',
+        revisionHistory: ['r1'],
+        sheetsById: {
+            Scene: {
+                staticOverrides: { byObject: { 'Y Bot': { position: { x: 1, y: 0, z: 2 } } } },
+                sequence: {
+                    type: 'PositionalSequence',
+                    length: 10,
+                    subUnitsPerUnit: 30,
+                    tracksByObject: {},
+                },
+            },
+        },
+    };
+}
+function makeScene({ withStudio = true } = {}) {
+    const project = getProject(`agent-project-${++projectSeq}`);
+    const sheet = project.sheet('Scene');
+    const content = fakeSaveFileContent();
+    const createContentOfSaveFile = jest.fn(() => content);
+    const studio = { createContentOfSaveFile };
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => (withStudio ? studio : undefined),
+        subscribeHistoric: () => () => { },
+    });
+    const registry = new AgentCommandRegistry();
+    registerProjectCommands(registry, runtime);
+    cleanups.push(() => runtime.dispose());
+    return { project, registry, runtime, content, createContentOfSaveFile };
+}
+test('exportState 以项目 ID 调 createContentOfSaveFile 并返回存档内容', async () => {
+    const { project, registry, content, createContentOfSaveFile } = makeScene();
+    const result = (await registry.execute('project.exportState', {}, ctx()));
+    expect(createContentOfSaveFile).toHaveBeenCalledTimes(1);
+    expect(createContentOfSaveFile).toHaveBeenCalledWith(project.address.projectId);
+    expect(result.projectId).toBe(project.address.projectId);
+    expect(result.content).toEqual(content);
+});
+test('exportState 返回深拷贝:改返回值不影响 studio 持有的存档对象', async () => {
+    const { registry, content } = makeScene();
+    const result = (await registry.execute('project.exportState', {}, ctx()));
+    expect(result.content).not.toBe(content);
+    expect(result.content.sheetsById).not.toBe(content.sheetsById);
+    // 篡改返回值的深层节点,源对象必须原样
+    result.content.sheetsById.Scene.staticOverrides.byObject['Y Bot'].position.x =
+        999;
+    result.content.revisionHistory.push('mutated');
+    expect(content.sheetsById.Scene.staticOverrides.byObject['Y Bot'].position.x).toBe(1);
+    expect(content.revisionHistory).toEqual(['r1']);
+});
+test('exportState 结果只含 projectId/content,不夹带会话或任务状态', async () => {
+    const { registry, content } = makeScene();
+    const result = (await registry.execute('project.exportState', {}, ctx()));
+    expect(result).toBeDefined();
+    // 顶层结构恰好两个键:不出现 Library 条目、activeCamera、PIP、任务状态
+    expect(Object.keys(result).sort()).toEqual(['content', 'projectId']);
+    // 存档内容就是 createContentOfSaveFile 的深拷贝,不多不少
+    expect(result.content).toEqual(content);
+    const serialized = JSON.stringify(result);
+    for (const sessionKey of [
+        'activeCamera',
+        'pipVisible',
+        'shotView',
+        'library',
+        'jobs',
+        'placing',
+        'editingPath',
+    ]) {
+        expect(serialized.includes(sessionKey)).toBe(false);
+    }
+});
+test('Studio 未初始化时 exportState 返回 API_NOT_READY', async () => {
+    const { registry } = makeScene({ withStudio: false });
+    await expect(registry.execute('project.exportState', {}, ctx())).rejects.toMatchObject({ code: 'API_NOT_READY' });
+});
+test('会话销毁后 exportState 返回 API_DISPOSED', async () => {
+    const { registry, runtime } = makeScene();
+    runtime.dispose();
+    await expect(registry.execute('project.exportState', {}, ctx())).rejects.toMatchObject({ code: 'API_DISPOSED' });
+});
+test('describe() 中 project.exportState 标记 query/project、undoable:none', () => {
+    const { registry } = makeScene();
+    const command = registry
+        .describe()
+        .commands.find((c) => c.name === 'project.exportState');
+    expect(command).toBeDefined();
+    expect(command).toMatchObject({
+        kind: 'query',
+        stateDomain: 'project',
+        undoable: 'none',
+    });
+});

package/dist/agent/commands/revision.realStudio.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * revision 返回时机的真实 Studio 行为测试(2026-10-19,F2 修复):
+ * 写命令(含 history.undo/redo)同步读 runtime.revision 拿到的是
+ * 写入前的值——historic 指针的 onChange 监听经 prism.onChange 排到
+ * core ticker 的下一 tick(prism.ts onThisOrNextTick),只有第一次
+ * 事务在 node 环境恰遇 dormant→active 的 start() 补 tick 才碰巧同步。
+ * 修复:写命令一律等一个 core tick 再读,返回值反映本次写入,
+ * expectedRevision 链式调用不错误冲突。
+ *
+ * 与 objects.test.ts / history.test.ts(假 Studio,验调用形状)互补:
+ * 本文件用真实 historic 订阅(onChange(pointers.historic))验端到端。
+ */
+import '@dreamerbird/studio';
+//# sourceMappingURL=revision.realStudio.test.d.ts.map

package/dist/agent/commands/revision.realStudio.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision.realStudio.test.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/revision.realStudio.test.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AACH,OAAO,qBAAqB,CAAA"}

package/dist/agent/commands/revision.realStudio.test.js

@@ -0,0 +1,129 @@
+/* eslint-disable import/no-extraneous-dependencies */
+/**
+ * revision 返回时机的真实 Studio 行为测试(2026-10-19,F2 修复):
+ * 写命令(含 history.undo/redo)同步读 runtime.revision 拿到的是
+ * 写入前的值——historic 指针的 onChange 监听经 prism.onChange 排到
+ * core ticker 的下一 tick(prism.ts onThisOrNextTick),只有第一次
+ * 事务在 node 环境恰遇 dormant→active 的 start() 补 tick 才碰巧同步。
+ * 修复:写命令一律等一个 core tick 再读,返回值反映本次写入,
+ * expectedRevision 链式调用不错误冲突。
+ *
+ * 与 objects.test.ts / history.test.ts(假 Studio,验调用形状)互补:
+ * 本文件用真实 historic 订阅(onChange(pointers.historic))验端到端。
+ */
+import '@dreamerbird/studio';
+import theatre, { getProject, onChange, types as t, val } from '@dreamerbird/core';
+import { privateAPI } from '@dreamerbird/core/privateAPIs';
+import { globals } from '@dreamerbird/core/globals';
+import getStudio from '@dreamerbird/studio/getStudio';
+import { getCoreTicker } from '@dreamerbird/core/coreTicker';
+import { PLACEMENTS_REGISTRY_KEY } from '../../PlacementManager';
+import { AgentCommandRegistry } from '../registry';
+import { createAgentRuntime } from '../runtime';
+import * as objectRuntime from '../runtime/objectRuntime';
+import { registerHistoryCommands } from './history';
+import { registerObjectCommands } from './objects';
+const studio = getStudio();
+void theatre.init({ studio: true, usePersistentStorage: false });
+let projectSeq = 0;
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+const cleanups = [];
+afterEach(() => {
+    while (cleanups.length)
+        cleanups.pop()();
+});
+function setup() {
+    const project = getProject(`agent-revision-real-${++projectSeq}`, {
+        state: {
+            definitionVersion: globals.currentProjectStateDefinitionVersion,
+            sheetsById: {
+                Scene: {
+                    staticOverrides: { byObject: {} },
+                    sequence: {
+                        type: 'PositionalSequence',
+                        length: 10,
+                        subUnitsPerUnit: 30,
+                        tracksByObject: {},
+                    },
+                },
+            },
+        },
+    });
+    getCoreTicker().tick();
+    const sheet = project.sheet('Scene');
+    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(1), y: t.number(2), z: t.number(3) }),
+    });
+    objectRuntime.registerSceneSheetObject('model:Foo', obj);
+    cleanups.push(() => objectRuntime.unregisterSceneSheetObject('model:Foo', obj));
+    // 真实 historic 订阅:revision 只随 onChange(pointers.historic) 通知递增
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => studio,
+        subscribeHistoric: (listener) => onChange(privateAPI(project).pointers.historic, () => listener()),
+    });
+    const registry = new AgentCommandRegistry();
+    registerObjectCommands(registry, runtime);
+    registerHistoryCommands(registry, runtime);
+    return { project, runtime, registry, obj: obj };
+}
+test('机制佐证:historic 通知是 tick 调度的,事务后同步读拿到写入前的值', async () => {
+    const { project, runtime, obj } = setup();
+    await project.ready;
+    // 打底一笔 + 冲刷:排除 dormant→active 时 start() 同步补 tick 的特例,
+    // 进入生产的常态(ticker active,通知排下一 tick)
+    studio.transaction(({ set }) => set(obj.props.position, { x: 0, y: 0, z: 0 }));
+    getCoreTicker().tick();
+    const before = runtime.revision;
+    studio.transaction(({ set }) => set(obj.props.position, { x: 9, y: 9, z: 9 }));
+    // 通知尚未触发:同步读滞后一笔(修复前写命令返回的就是这个过期值)
+    expect(runtime.revision).toBe(before);
+    getCoreTicker().tick();
+    expect(runtime.revision).toBe(before + 1);
+});
+test('写命令返回写入后的 revision,expectedRevision 可连续链式写入', async () => {
+    const { project, runtime, registry, obj } = setup();
+    await project.ready;
+    const baseline = runtime.revision;
+    const u1 = (await registry.execute('objects.update', { objectId: 'model:Foo', props: { position: { x: 5, y: 0, z: 0 } } }, ctx()));
+    expect(u1.revision).toBe(baseline + 1);
+    // 链式:上一笔的返回 revision 直接作下一笔的 expectedRevision
+    const u2 = (await registry.execute('objects.update', {
+        objectId: 'model:Foo',
+        props: { position: { x: 6, y: 0, z: 0 } },
+        expectedRevision: u1.revision,
+    }, ctx()));
+    expect(u2.revision).toBe(u1.revision + 1);
+    const u3 = (await registry.execute('objects.update', {
+        objectId: 'model:Foo',
+        props: { position: { x: 7, y: 0, z: 0 } },
+        expectedRevision: u2.revision,
+    }, ctx()));
+    expect(u3.revision).toBe(u2.revision + 1);
+    expect(val(obj.props.position)).toEqual({ x: 7, y: 0, z: 0 });
+});
+test('history.undo 返回 undo 后的 revision;可继续链式写入', async () => {
+    const { project, registry, obj } = setup();
+    await project.ready;
+    const u1 = (await registry.execute('objects.update', { objectId: 'model:Foo', props: { position: { x: 5, y: 0, z: 0 } } }, ctx()));
+    expect(val(obj.props.position)).toEqual({ x: 5, y: 0, z: 0 });
+    // undo 也改 historic:返回 revision 必须反映 undo 本身
+    const u2 = (await registry.execute('history.undo', { expectedRevision: u1.revision }, ctx()));
+    expect(u2.revision).toBe(u1.revision + 1);
+    expect(val(obj.props.position)).toEqual({ x: 1, y: 2, z: 3 });
+    // undo 后的 revision 可直接续链
+    await expect(registry.execute('objects.update', {
+        objectId: 'model:Foo',
+        props: { position: { x: 8, y: 0, z: 0 } },
+        expectedRevision: u2.revision,
+    }, ctx())).resolves.toMatchObject({ revision: u2.revision + 1 });
+});

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

@@ -0,0 +1,32 @@
+import type { SceneObjectSummary, SceneSnapshot } from '../objectResolver';
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+import type { SceneObjectId } from '../types';
+export type { SceneObjectSummary, SceneSnapshot } from '../objectResolver';
+/** 场景查询门面 */
+export type SceneApi = {
+    getSnapshot(): Promise<SceneSnapshot>;
+};
+/** 完整对象门面类型;本任务实现 list/get,update/delete 由后续任务实现 */
+export type ObjectsApi = {
+    list(): Promise<SceneObjectSummary[]>;
+    get(args: {
+        objectId: SceneObjectId;
+    }): Promise<SceneObjectSummary>;
+    update(args: {
+        objectId: SceneObjectId;
+        props: Record<string, unknown>;
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    delete(args: {
+        objectId: SceneObjectId;
+        expectedRevision?: number;
+    }): Promise<{
+        deleted: SceneObjectId;
+        revision: number;
+    }>;
+};
+export declare function registerSceneCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=scene.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/scene.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAC,kBAAkB,EAAE,aAAa,EAAC,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAE5C,OAAO,KAAK,EAAa,aAAa,EAAC,MAAM,UAAU,CAAA;AAEvD,YAAY,EAAC,kBAAkB,EAAE,aAAa,EAAC,MAAM,mBAAmB,CAAA;AAExE,aAAa;AACb,MAAM,MAAM,QAAQ,GAAG;IACrB,WAAW,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;CACtC,CAAA;AAED,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAA;IACrC,GAAG,CAAC,IAAI,EAAE;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IACjE,MAAM,CAAC,IAAI,EAAE;QACX,QAAQ,EAAE,aAAa,CAAA;QACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IAC/B,MAAM,CAAC,IAAI,EAAE;QACX,QAAQ,EAAE,aAAa,CAAA;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B,GAAG,OAAO,CAAC;QAAC,OAAO,EAAE,aAAa,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CACxD,CAAA;AAkCD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CA8DN"}

package/dist/agent/commands/scene.js

@@ -0,0 +1,100 @@
+/**
+ * 场景查询命令(2026-10-17,Task 4):scene.getSnapshot / objects.list /
+ * objects.get。全部 query/project、undoable:none,execute 前先
+ * runtime.assertActive();无副作用由 objectResolver 保证。
+ *
+ * 同时产出 SceneApi/ObjectsApi 门面类型(Task 15 由同名命令转发实现);
+ * ObjectsApi 的 update/delete 由后续任务补同一接口。
+ */
+import { getSceneObjectSummary, listSceneObjects } from '../objectResolver';
+import { requireObject, requireString } from '../validation';
+const summarySchema = {
+    type: 'object',
+    properties: {
+        id: { type: 'string', description: '带类型场景对象 ID,如 model:Y Bot' },
+        kind: { type: 'string', enum: ['model', 'camera', 'anchor', 'path'] },
+        key: { type: 'string' },
+        props: {
+            type: 'object',
+            description: '当前求值属性的深拷贝;未挂载为 null',
+        },
+        mounted: { type: 'boolean' },
+    },
+    required: ['id', 'kind', 'key', 'props', 'mounted'],
+};
+const emptyInput = { type: 'object', additionalProperties: false };
+const objectIdInput = {
+    type: 'object',
+    properties: {
+        objectId: { type: 'string', description: '带类型场景对象 ID,如 model:Y Bot' },
+    },
+    required: ['objectId'],
+    additionalProperties: false,
+};
+/** 无参命令的运行时校验:允许省略参数或空对象 */
+function noArgs(value) {
+    if (value === undefined || value === null)
+        return {};
+    return requireObject(value);
+}
+export function registerSceneCommands(registry, runtime) {
+    registry.register({
+        name: 'scene.getSnapshot',
+        kind: 'query',
+        stateDomain: 'project',
+        undoable: 'none',
+        inputSchema: emptyInput,
+        outputSchema: {
+            type: 'object',
+            properties: {
+                revision: { type: 'number' },
+                objects: { type: 'array', items: summarySchema },
+            },
+            required: ['revision', 'objects'],
+        },
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT'],
+        validate: noArgs,
+        execute: async () => {
+            runtime.assertActive();
+            return {
+                revision: runtime.revision,
+                objects: listSceneObjects(runtime.sheet),
+            };
+        },
+    });
+    registry.register({
+        name: 'objects.list',
+        kind: 'query',
+        stateDomain: 'project',
+        undoable: 'none',
+        inputSchema: emptyInput,
+        outputSchema: { type: 'array', items: summarySchema },
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT'],
+        validate: noArgs,
+        execute: async () => {
+            runtime.assertActive();
+            return listSceneObjects(runtime.sheet);
+        },
+    });
+    registry.register({
+        name: 'objects.get',
+        kind: 'query',
+        stateDomain: 'project',
+        undoable: 'none',
+        inputSchema: objectIdInput,
+        outputSchema: summarySchema,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'INVALID_ID_KIND',
+            'OBJECT_NOT_FOUND',
+        ],
+        validate: (value) => ({
+            objectId: requireString(requireObject(value), 'objectId'),
+        }),
+        execute: async (args) => {
+            runtime.assertActive();
+            return getSceneObjectSummary(runtime.sheet, args.objectId);
+        },
+    });
+}

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

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

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

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

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

@@ -0,0 +1,147 @@
+/**
+ * scene.getSnapshot / objects.list / objects.get(Task 4):
+ * 无副作用是核心契约 —— 查询只用 privateAPI(sheet).getObject 探测,
+ * 绝不创建注册表/路径对象,historic 状态序列化前后一致。
+ * 注册表有条目但运行时未挂载 → props:null, mounted:false,
+ * 而不是误报 OBJECT_NOT_FOUND。
+ */
+import { getProject, types as t, val } from '@dreamerbird/core';
+import { privateAPI } from '@dreamerbird/core/privateAPIs';
+import { pathExists } from '../../CameraPath';
+import { CAMERAS_REGISTRY_KEY } from '../../cameraRegistry';
+import { PLACEMENTS_REGISTRY_KEY } from '../../PlacementManager';
+import { AgentCommandRegistry } from '../registry';
+import { createAgentRuntime } from '../runtime';
+import { registerSceneSheetObject, unregisterSceneSheetObject, } from '../runtime/objectRuntime';
+import { registerSceneCommands } from './scene';
+let projectSeq = 0;
+function makeScene() {
+    const project = getProject(`agent-scene-${++projectSeq}`);
+    const sheet = project.sheet('Scene');
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => undefined,
+        subscribeHistoric: () => () => { },
+    });
+    const registry = new AgentCommandRegistry();
+    registerSceneCommands(registry, runtime);
+    return { project, sheet, registry, runtime };
+}
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+const REGISTRY_KEYS = ['Placements', 'Cameras', 'Anchors', 'Paths'];
+/** 四个业务注册表对象的存活探测(只读,不创建) */
+function peekRegistries(sheet) {
+    return REGISTRY_KEYS.map((key) => Boolean(privateAPI(sheet).getObject(key)));
+}
+/** historic 状态序列化:无副作用断言的底账 */
+function historicJson(project) {
+    return JSON.stringify(val(privateAPI(project).pointers.historic));
+}
+/** 测试布景:直接建注册表对象并写清单(initialValue 不需要 studio) */
+function seedPlacements(sheet, entries) {
+    const registry = sheet.object(PLACEMENTS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+    registry.initialValue = { list: JSON.stringify(entries) };
+}
+test('空场景查询无副作用:不创建注册表,不改 historic 状态', async () => {
+    const { project, sheet, registry } = makeScene();
+    expect(peekRegistries(sheet)).toEqual([false, false, false, false]);
+    const historicBefore = historicJson(project);
+    const snapshot = await registry.execute('scene.getSnapshot', {}, ctx());
+    expect(snapshot).toEqual({ revision: 1, objects: [] });
+    const list = await registry.execute('objects.list', {}, ctx());
+    expect(list).toEqual([]);
+    expect(peekRegistries(sheet)).toEqual([false, false, false, false]);
+    expect(historicJson(project)).toBe(historicBefore);
+});
+test('objects.get 不存在的路径:OBJECT_NOT_FOUND,且不创建路径对象', async () => {
+    const { sheet, registry } = makeScene();
+    expect(pathExists(sheet, 'missing')).toBe(false);
+    await expect(registry.execute('objects.get', { objectId: 'path:missing' }, ctx())).rejects.toMatchObject({
+        code: 'OBJECT_NOT_FOUND',
+        details: { objectId: 'path:missing', kind: 'path' },
+    });
+    expect(pathExists(sheet, 'missing')).toBe(false);
+});
+test('objects.get 无效 ID 前缀返回 INVALID_ID_KIND', async () => {
+    const { registry } = makeScene();
+    await expect(registry.execute('objects.get', { objectId: 'foo:A' }, ctx())).rejects.toMatchObject({ code: 'INVALID_ID_KIND' });
+});
+test('objects.get 注册表里没有的模型:OBJECT_NOT_FOUND,details 含 objectId/kind', async () => {
+    const { registry } = makeScene();
+    await expect(registry.execute('objects.get', { objectId: 'model:Nope' }, ctx())).rejects.toMatchObject({
+        code: 'OBJECT_NOT_FOUND',
+        details: { objectId: 'model:Nope', kind: 'model' },
+    });
+});
+test('注册表有条目但运行时未挂载:props:null, mounted:false', async () => {
+    const { sheet, registry } = makeScene();
+    seedPlacements(sheet, [{ key: 'Foo', position: { x: 1, y: 2, z: 3 } }]);
+    const got = await registry.execute('objects.get', { objectId: 'model:Foo' }, ctx());
+    expect(got).toEqual({
+        id: 'model:Foo',
+        kind: 'model',
+        key: 'Foo',
+        props: null,
+        mounted: false,
+    });
+    const list = await registry.execute('objects.list', {}, ctx());
+    expect(list).toEqual([
+        { id: 'model:Foo', kind: 'model', key: 'Foo', props: null, mounted: false },
+    ]);
+});
+test('已挂载对象返回当前求值属性的深拷贝', async () => {
+    const { sheet, registry } = makeScene();
+    seedPlacements(sheet, [{ key: 'Foo', position: { x: 0, y: 0, z: 0 } }]);
+    const obj = sheet.object('Foo', {
+        position: t.compound({ x: t.number(1), y: t.number(2), z: t.number(3) }),
+    });
+    registerSceneSheetObject('model:Foo', obj);
+    try {
+        const got = (await registry.execute('objects.get', { objectId: 'model:Foo' }, ctx()));
+        expect(got.mounted).toBe(true);
+        expect(got.props).toEqual({ position: { x: 1, y: 2, z: 3 } });
+        // 深拷贝:改返回值不得影响 theatre 对象本体
+        got.props.position.x = 99;
+        expect(obj.value.position.x).toBe(1);
+    }
+    finally {
+        unregisterSceneSheetObject('model:Foo', obj);
+    }
+});
+test('快照带 revision 且涵盖四种业务对象', async () => {
+    const { sheet, registry } = makeScene();
+    seedPlacements(sheet, [{ key: 'Foo', position: { x: 0, y: 0, z: 0 } }]);
+    const cameras = sheet.object(CAMERAS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+    cameras.initialValue = { list: JSON.stringify([{ cameraKey: 'Cam 1' }]) };
+    const snapshot = (await registry.execute('scene.getSnapshot', {}, ctx()));
+    expect(snapshot.revision).toBe(1);
+    expect(snapshot.objects.map((o) => o.id)).toEqual([
+        'model:Foo',
+        'camera:Cam 1',
+    ]);
+});
+test('会话销毁后查询返回 API_DISPOSED', async () => {
+    const { registry, runtime } = makeScene();
+    runtime.dispose();
+    await expect(registry.execute('scene.getSnapshot', {}, ctx())).rejects.toMatchObject({ code: 'API_DISPOSED' });
+    await expect(registry.execute('objects.list', {}, ctx())).rejects.toMatchObject({ code: 'API_DISPOSED' });
+});
+test('describe() 中查询命令标记 query/project', () => {
+    const { registry } = makeScene();
+    const described = registry.describe();
+    const byName = new Map(described.commands.map((c) => [c.name, c]));
+    for (const name of ['scene.getSnapshot', 'objects.list', 'objects.get']) {
+        const command = byName.get(name);
+        expect(command).toBeDefined();
+        expect(command).toMatchObject({
+            kind: 'query',
+            stateDomain: 'project',
+            undoable: 'none',
+        });
+    }
+});

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

@@ -0,0 +1,21 @@
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+import type { SceneObjectId } from '../types';
+declare module '../runtime' {
+    interface AgentSceneRuntimeHandlers {
+        /** 清理路径控制点的会话选择(CameraScene 绑定;selection.clear 时调用) */
+        clearPathPointSelection(): void;
+    }
+}
+/** 选择门面(Task 15 由同名命令转发实现) */
+export type SelectionApi = {
+    get(): Promise<{
+        objectIds: SceneObjectId[];
+    }>;
+    selectObject(args: {
+        objectId: SceneObjectId;
+    }): Promise<void>;
+    clear(): Promise<void>;
+};
+export declare function registerSelectionCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=selection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selection.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/selection.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAA;AAG5C,OAAO,KAAK,EAAa,aAAa,EAAC,MAAM,UAAU,CAAA;AAEvD,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,yBAAyB;QACjC,uDAAuD;QACvD,uBAAuB,IAAI,IAAI,CAAA;KAChC;CACF;AAED,8BAA8B;AAC9B,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,IAAI,OAAO,CAAC;QAAC,SAAS,EAAE,aAAa,EAAE,CAAA;KAAC,CAAC,CAAA;IAC5C,YAAY,CAAC,IAAI,EAAE;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB,CAAA;AA4BD,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAkFN"}