@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/agent/commands/view.js

@@ -0,0 +1,229 @@
+import { AgentApiError } from '../errors';
+import { getDirectorView } from '../runtime/directorView';
+import { requireBoolean, requireFiniteNumber, requireObject } from '../validation';
+const emptyInput = { type: 'object', additionalProperties: false };
+const voidOutput = { type: 'object', additionalProperties: false };
+const getStateOutput = {
+    type: 'object',
+    properties: {
+        activeCameraKey: {
+            type: 'string',
+            description: '活动相机 key;无活动相机为 null',
+        },
+        shotView: { type: 'boolean' },
+        pipVisible: { type: 'boolean' },
+        editingPath: {
+            type: 'string',
+            description: '正在编辑的路径 key;未编辑为 null',
+        },
+        gizmoMode: {
+            type: 'string',
+            enum: ['select', 'translate', 'rotate', 'scale'],
+        },
+        studioHidden: { type: 'boolean' },
+    },
+    required: [
+        'activeCameraKey',
+        'shotView',
+        'pipVisible',
+        'editingPath',
+        'gizmoMode',
+        'studioHidden',
+    ],
+};
+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;
+}
+/** 已注册的导演控制器;未注册 API_NOT_READY(MainOrbitControls 未挂载) */
+function requireDirectorView() {
+    const controller = getDirectorView();
+    if (!controller) {
+        throw new AgentApiError('API_NOT_READY', '导演视角控制器未注册(场景轨道控制器尚未挂载)');
+    }
+    return controller;
+}
+function requireViewHandlers(runtime) {
+    const handlers = runtime.handlers;
+    if (!handlers.getViewState ||
+        !handlers.setShotView ||
+        !handlers.setPipVisible) {
+        throw new AgentApiError('SCENE_UNAVAILABLE', 'Scene Runtime 未绑定视图 handler,无法读写视图会话态');
+    }
+    return handlers;
+}
+export function registerViewCommands(registry, runtime) {
+    registry.register({
+        name: 'view.getState',
+        kind: 'query',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: emptyInput,
+        outputSchema: getStateOutput,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'SCENE_UNAVAILABLE'],
+        validate: noArgs,
+        execute: async () => {
+            runtime.assertActive();
+            const handlers = requireViewHandlers(runtime);
+            const studio = requireStudio(runtime);
+            return { ...handlers.getViewState(), studioHidden: studio.ui.isHidden };
+        },
+    });
+    registry.register({
+        name: 'view.setShotView',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                on: {
+                    type: 'boolean',
+                    description: 'true = 进入镜头视角,false = 回到导演视角',
+                },
+            },
+            required: ['on'],
+            additionalProperties: false,
+        },
+        outputSchema: voidOutput,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'SCENE_UNAVAILABLE'],
+        validate: (value) => ({ on: requireBoolean(requireObject(value), 'on') }),
+        execute: async (args) => {
+            runtime.assertActive();
+            requireViewHandlers(runtime).setShotView({ on: args.on });
+        },
+    });
+    registry.register({
+        name: 'view.setPipVisible',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                visible: { type: 'boolean', description: '画中画是否可见' },
+            },
+            required: ['visible'],
+            additionalProperties: false,
+        },
+        outputSchema: voidOutput,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'SCENE_UNAVAILABLE'],
+        validate: (value) => ({
+            visible: requireBoolean(requireObject(value), 'visible'),
+        }),
+        execute: async (args) => {
+            runtime.assertActive();
+            requireViewHandlers(runtime).setPipVisible({ visible: args.visible });
+        },
+    });
+    registry.register({
+        name: 'view.orbit',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                deltaTheta: {
+                    type: 'number',
+                    description: '方位角增量(弧度,正值绕瞄准点逆时针,俯视)',
+                },
+                deltaPhi: {
+                    type: 'number',
+                    description: '极角增量(弧度,正值向水平方向下压)',
+                },
+            },
+            required: ['deltaTheta', 'deltaPhi'],
+            additionalProperties: false,
+        },
+        outputSchema: voidOutput,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'API_NOT_READY'],
+        validate: (value) => {
+            const args = requireObject(value);
+            return {
+                deltaTheta: requireFiniteNumber(args.deltaTheta, 'deltaTheta'),
+                deltaPhi: requireFiniteNumber(args.deltaPhi, 'deltaPhi'),
+            };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            requireDirectorView().orbit(args);
+        },
+    });
+    registry.register({
+        name: 'view.pan',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                deltaX: { type: 'number', description: '沿相机右方向平移(世界单位)' },
+                deltaY: { type: 'number', description: '沿相机上方向平移(世界单位)' },
+            },
+            required: ['deltaX', 'deltaY'],
+            additionalProperties: false,
+        },
+        outputSchema: voidOutput,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'API_NOT_READY'],
+        validate: (value) => {
+            const args = requireObject(value);
+            return {
+                deltaX: requireFiniteNumber(args.deltaX, 'deltaX'),
+                deltaY: requireFiniteNumber(args.deltaY, 'deltaY'),
+            };
+        },
+        execute: async (args) => {
+            runtime.assertActive();
+            requireDirectorView().pan(args);
+        },
+    });
+    registry.register({
+        name: 'view.dolly',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                delta: {
+                    type: 'number',
+                    description: '沿视线的距离增量(正值 = 靠近瞄准点,负值 = 拉远)',
+                },
+            },
+            required: ['delta'],
+            additionalProperties: false,
+        },
+        outputSchema: voidOutput,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'API_NOT_READY'],
+        validate: (value) => ({
+            delta: requireFiniteNumber(requireObject(value).delta, 'delta'),
+        }),
+        execute: async (args) => {
+            runtime.assertActive();
+            requireDirectorView().dolly(args);
+        },
+    });
+    registry.register({
+        name: 'view.reset',
+        kind: 'mutation',
+        stateDomain: 'session',
+        undoable: 'none',
+        inputSchema: emptyInput,
+        outputSchema: voidOutput,
+        errorCodes: ['API_DISPOSED', 'INVALID_ARGUMENT', 'API_NOT_READY'],
+        validate: noArgs,
+        execute: async () => {
+            runtime.assertActive();
+            requireDirectorView().reset();
+        },
+    });
+}

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

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

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

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

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

@@ -0,0 +1,347 @@
+/**
+ * view / ui 命令(2026-10-17,Task 12):
+ * view.getState / setShotView / setPipVisible / orbit / pan / dolly / reset
+ * + ui.hide / restore / setLeftStripHidden / openPanel / closePanel /
+ * setGizmoMode。
+ *
+ * 全部 session 域、undoable:none(spec 9 view/ui 行 + 8.6.4:视图/UI 会话
+ * 操作不进撤销)。视图会话态与面板/gizmo 经 Scene Runtime handler
+ * (生产由 CameraScene 绑定,Task 15 接线;测试用假 handler,形状与接线
+ * 后的绑定一致);orbit/pan/dolly/reset 转发到 directorView 模块注册的
+ * 导演控制器(MainOrbitControls 挂载时登记),未注册返回 API_NOT_READY,
+ * 不静默成功。studio 显隐走公开 studio.ui 方法。
+ *
+ * 布景同 selection.test.ts:真实 core project/sheet + 注入式假 studio
+ * (runtime.getStudio),node 环境,无需 doMock。
+ */
+import { getProject } from '@dreamerbird/core';
+import { AgentCommandRegistry } from '../registry';
+import { createAgentRuntime } from '../runtime';
+import { getDirectorView, registerDirectorView } from '../runtime/directorView';
+import { registerUiCommands } from './ui';
+import { registerViewCommands } from './view';
+let projectSeq = 0;
+const cleanups = [];
+afterEach(() => {
+    while (cleanups.length)
+        cleanups.pop()();
+});
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+function makeScene({ withStudio = true } = {}) {
+    const project = getProject(`agent-view-${++projectSeq}`);
+    const sheet = project.sheet('Scene');
+    const ui = {
+        hide: jest.fn(),
+        restore: jest.fn(),
+        isHidden: false,
+        setLeftStripHidden: jest.fn(),
+    };
+    const studio = { ui };
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => (withStudio ? studio : undefined),
+        subscribeHistoric: () => () => { },
+    });
+    const registry = new AgentCommandRegistry();
+    registerViewCommands(registry, runtime);
+    registerUiCommands(registry, runtime);
+    cleanups.push(() => runtime.dispose());
+    return { project, sheet, registry, runtime, ui };
+}
+/** 绑定 CameraScene 侧的视图会话 handler(假实现,形状同生产绑定) */
+function bindViewHandlers(runtime, state) {
+    const setShotView = jest.fn();
+    const setPipVisible = jest.fn();
+    cleanups.push(runtime.bindHandlers({
+        getViewState: () => state,
+        setShotView,
+        setPipVisible,
+    }));
+    return { setShotView, setPipVisible };
+}
+/** 登记导演控制器假实现(MainOrbitControls 生产登记的同形状替身) */
+function registerFakeController() {
+    const controller = {
+        orbit: jest.fn(),
+        pan: jest.fn(),
+        dolly: jest.fn(),
+        reset: jest.fn(),
+    };
+    cleanups.push(registerDirectorView(controller));
+    return controller;
+}
+// ── view.getState ──────────────────────────────────────────────
+test('view.getState 返回活动相机/镜头视角/PIP/路径编辑/gizmo/studio 显隐', async () => {
+    const { registry, runtime, ui } = makeScene();
+    ui.isHidden = true;
+    bindViewHandlers(runtime, {
+        activeCameraKey: 'Cam 1',
+        shotView: true,
+        pipVisible: false,
+        editingPath: 'Fly Around',
+        gizmoMode: 'rotate',
+    });
+    const state = await registry.execute('view.getState', {}, ctx());
+    expect(state).toEqual({
+        activeCameraKey: 'Cam 1',
+        shotView: true,
+        pipVisible: false,
+        editingPath: 'Fly Around',
+        gizmoMode: 'rotate',
+        studioHidden: true,
+    });
+});
+test('view.getState 无活动相机/未编辑路径时回 null 字段', async () => {
+    const { registry, runtime } = makeScene();
+    bindViewHandlers(runtime, {
+        activeCameraKey: null,
+        shotView: false,
+        pipVisible: true,
+        editingPath: null,
+        gizmoMode: 'select',
+    });
+    const state = await registry.execute('view.getState', {}, ctx());
+    expect(state).toEqual({
+        activeCameraKey: null,
+        shotView: false,
+        pipVisible: true,
+        editingPath: null,
+        gizmoMode: 'select',
+        studioHidden: false,
+    });
+});
+test('view.getState 视图 handler 未绑定返回 SCENE_UNAVAILABLE', async () => {
+    const { registry } = makeScene();
+    await expect(registry.execute('view.getState', {}, ctx())).rejects.toMatchObject({
+        code: 'SCENE_UNAVAILABLE',
+    });
+});
+test('view.getState Studio 不可用返回 SCENE_UNAVAILABLE', async () => {
+    const { registry, runtime } = makeScene({ withStudio: false });
+    bindViewHandlers(runtime, {
+        activeCameraKey: null,
+        shotView: false,
+        pipVisible: true,
+        editingPath: null,
+        gizmoMode: 'select',
+    });
+    await expect(registry.execute('view.getState', {}, ctx())).rejects.toMatchObject({
+        code: 'SCENE_UNAVAILABLE',
+    });
+});
+// ── view.setShotView / setPipVisible ───────────────────────────
+test('view.setShotView 转发到 Scene Runtime handler', async () => {
+    const { registry, runtime } = makeScene();
+    const { setShotView } = bindViewHandlers(runtime, {
+        activeCameraKey: null,
+        shotView: false,
+        pipVisible: true,
+        editingPath: null,
+        gizmoMode: 'select',
+    });
+    await registry.execute('view.setShotView', { on: true }, ctx());
+    expect(setShotView).toHaveBeenCalledWith({ on: true });
+});
+test('view.setPipVisible 转发到 Scene Runtime handler', async () => {
+    const { registry, runtime } = makeScene();
+    const { setPipVisible } = bindViewHandlers(runtime, {
+        activeCameraKey: null,
+        shotView: false,
+        pipVisible: true,
+        editingPath: null,
+        gizmoMode: 'select',
+    });
+    await registry.execute('view.setPipVisible', { visible: false }, ctx());
+    expect(setPipVisible).toHaveBeenCalledWith({ visible: false });
+});
+test('view.setShotView 非布尔参数返回 INVALID_ARGUMENT,不触达 handler', async () => {
+    const { registry, runtime } = makeScene();
+    const { setShotView } = bindViewHandlers(runtime, {
+        activeCameraKey: null,
+        shotView: false,
+        pipVisible: true,
+        editingPath: null,
+        gizmoMode: 'select',
+    });
+    await expect(registry.execute('view.setShotView', { on: 'yes' }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    expect(setShotView).not.toHaveBeenCalled();
+});
+test('view.setPipVisible handler 未绑定返回 SCENE_UNAVAILABLE', async () => {
+    const { registry } = makeScene();
+    await expect(registry.execute('view.setPipVisible', { visible: true }, ctx())).rejects.toMatchObject({ code: 'SCENE_UNAVAILABLE' });
+});
+// ── view.orbit / pan / dolly / reset ───────────────────────────
+test('view.orbit 转发到已注册导演控制器', async () => {
+    const { registry } = makeScene();
+    const controller = registerFakeController();
+    await registry.execute('view.orbit', { deltaTheta: 0.3, deltaPhi: -0.1 }, ctx());
+    expect(controller.orbit).toHaveBeenCalledWith({
+        deltaTheta: 0.3,
+        deltaPhi: -0.1,
+    });
+});
+test('view.pan / dolly / reset 转发到已注册导演控制器', async () => {
+    const { registry } = makeScene();
+    const controller = registerFakeController();
+    await registry.execute('view.pan', { deltaX: 1.5, deltaY: -2 }, ctx());
+    await registry.execute('view.dolly', { delta: 3 }, ctx());
+    await registry.execute('view.reset', {}, ctx());
+    expect(controller.pan).toHaveBeenCalledWith({ deltaX: 1.5, deltaY: -2 });
+    expect(controller.dolly).toHaveBeenCalledWith({ delta: 3 });
+    expect(controller.reset).toHaveBeenCalledTimes(1);
+});
+test('导演控制器未注册时 orbit/pan/dolly/reset 返回 API_NOT_READY', async () => {
+    const { registry } = makeScene();
+    expect(getDirectorView()).toBeUndefined();
+    await expect(registry.execute('view.orbit', { deltaTheta: 0.1, deltaPhi: 0 }, ctx())).rejects.toMatchObject({ code: 'API_NOT_READY' });
+    await expect(registry.execute('view.pan', { deltaX: 1, deltaY: 0 }, ctx())).rejects.toMatchObject({ code: 'API_NOT_READY' });
+    await expect(registry.execute('view.dolly', { delta: 1 }, ctx())).rejects.toMatchObject({ code: 'API_NOT_READY' });
+    await expect(registry.execute('view.reset', {}, ctx())).rejects.toMatchObject({
+        code: 'API_NOT_READY',
+    });
+});
+test('orbit/pan/dolly 拒绝非有限数字,不触达控制器', async () => {
+    const { registry } = makeScene();
+    const controller = registerFakeController();
+    await expect(registry.execute('view.orbit', { deltaTheta: NaN, deltaPhi: 0 }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    await expect(registry.execute('view.orbit', { deltaTheta: 0, deltaPhi: Infinity }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    await expect(registry.execute('view.pan', { deltaX: 0, deltaY: -Infinity }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    await expect(registry.execute('view.dolly', { delta: Number.NaN }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    expect(controller.orbit).not.toHaveBeenCalled();
+    expect(controller.pan).not.toHaveBeenCalled();
+    expect(controller.dolly).not.toHaveBeenCalled();
+});
+// ── ui.hide / restore / setLeftStripHidden ─────────────────────
+test('ui.hide / restore / setLeftStripHidden 走公开 studio.ui 方法', async () => {
+    const { registry, ui } = makeScene();
+    await registry.execute('ui.hide', {}, ctx());
+    await registry.execute('ui.restore', {}, ctx());
+    await registry.execute('ui.setLeftStripHidden', { hidden: true }, ctx());
+    expect(ui.hide).toHaveBeenCalledTimes(1);
+    expect(ui.restore).toHaveBeenCalledTimes(1);
+    expect(ui.setLeftStripHidden).toHaveBeenCalledWith(true);
+});
+test('Studio 不可用时 ui.hide / restore / setLeftStripHidden 返回 SCENE_UNAVAILABLE', async () => {
+    const { registry } = makeScene({ withStudio: false });
+    await expect(registry.execute('ui.hide', {}, ctx())).rejects.toMatchObject({
+        code: 'SCENE_UNAVAILABLE',
+    });
+    await expect(registry.execute('ui.restore', {}, ctx())).rejects.toMatchObject({
+        code: 'SCENE_UNAVAILABLE',
+    });
+    await expect(registry.execute('ui.setLeftStripHidden', { hidden: true }, ctx())).rejects.toMatchObject({ code: 'SCENE_UNAVAILABLE' });
+});
+test('ui.setLeftStripHidden 非布尔参数返回 INVALID_ARGUMENT', async () => {
+    const { registry, ui } = makeScene();
+    await expect(registry.execute('ui.setLeftStripHidden', { hidden: 1 }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    expect(ui.setLeftStripHidden).not.toHaveBeenCalled();
+});
+// ── ui.openPanel / closePanel ──────────────────────────────────
+test('ui.openPanel / closePanel 转发 model|pose|animation|path 到 handler', async () => {
+    const { registry, runtime } = makeScene();
+    const openPanel = jest.fn();
+    const closePanel = jest.fn();
+    cleanups.push(runtime.bindHandlers({ openPanel, closePanel }));
+    for (const panel of ['model', 'pose', 'animation', 'path']) {
+        await registry.execute('ui.openPanel', { panel }, ctx());
+        await registry.execute('ui.closePanel', { panel }, ctx());
+    }
+    expect(openPanel.mock.calls).toEqual([
+        [{ panel: 'model' }],
+        [{ panel: 'pose' }],
+        [{ panel: 'animation' }],
+        [{ panel: 'path' }],
+    ]);
+    expect(closePanel.mock.calls).toEqual([
+        [{ panel: 'model' }],
+        [{ panel: 'pose' }],
+        [{ panel: 'animation' }],
+        [{ panel: 'path' }],
+    ]);
+});
+test('ui.openPanel / closePanel 拒绝未知面板名', async () => {
+    const { registry, runtime } = makeScene();
+    const openPanel = jest.fn();
+    const closePanel = jest.fn();
+    cleanups.push(runtime.bindHandlers({ openPanel, closePanel }));
+    await expect(registry.execute('ui.openPanel', { panel: 'assets' }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    await expect(registry.execute('ui.closePanel', { panel: '' }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    expect(openPanel).not.toHaveBeenCalled();
+    expect(closePanel).not.toHaveBeenCalled();
+});
+test('ui.openPanel handler 未绑定返回 SCENE_UNAVAILABLE', async () => {
+    const { registry } = makeScene();
+    await expect(registry.execute('ui.openPanel', { panel: 'model' }, ctx())).rejects.toMatchObject({ code: 'SCENE_UNAVAILABLE' });
+});
+// ── ui.setGizmoMode ────────────────────────────────────────────
+test('ui.setGizmoMode 接受 select|translate|rotate|scale 并转发', async () => {
+    const { registry, runtime } = makeScene();
+    const setGizmoMode = jest.fn();
+    cleanups.push(runtime.bindHandlers({ setGizmoMode }));
+    for (const mode of ['select', 'translate', 'rotate', 'scale']) {
+        await registry.execute('ui.setGizmoMode', { mode }, ctx());
+    }
+    expect(setGizmoMode.mock.calls).toEqual([
+        [{ mode: 'select' }],
+        [{ mode: 'translate' }],
+        [{ mode: 'rotate' }],
+        [{ mode: 'scale' }],
+    ]);
+});
+test('ui.setGizmoMode 拒绝未知模式,不触达 handler', async () => {
+    const { registry, runtime } = makeScene();
+    const setGizmoMode = jest.fn();
+    cleanups.push(runtime.bindHandlers({ setGizmoMode }));
+    await expect(registry.execute('ui.setGizmoMode', { mode: 'fly' }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    expect(setGizmoMode).not.toHaveBeenCalled();
+});
+test('ui.setGizmoMode handler 未绑定返回 SCENE_UNAVAILABLE', async () => {
+    const { registry } = makeScene();
+    await expect(registry.execute('ui.setGizmoMode', { mode: 'select' }, ctx())).rejects.toMatchObject({ code: 'SCENE_UNAVAILABLE' });
+});
+// ── 会话销毁与元数据 ───────────────────────────────────────────
+test('会话销毁后 view/ui 命令返回 API_DISPOSED', async () => {
+    const { registry, runtime } = makeScene();
+    registerFakeController();
+    runtime.dispose();
+    await expect(registry.execute('view.getState', {}, ctx())).rejects.toMatchObject({
+        code: 'API_DISPOSED',
+    });
+    await expect(registry.execute('view.orbit', { deltaTheta: 0.1, deltaPhi: 0 }, ctx())).rejects.toMatchObject({ code: 'API_DISPOSED' });
+    await expect(registry.execute('ui.hide', {}, ctx())).rejects.toMatchObject({
+        code: 'API_DISPOSED',
+    });
+});
+test('describe() 中 view/ui 命令全部 session 域、undoable:none', () => {
+    const { registry } = makeScene();
+    const byName = new Map(registry.describe().commands.map((c) => [c.name, c]));
+    const expected = {
+        'view.getState': 'query',
+        'view.setShotView': 'mutation',
+        'view.setPipVisible': 'mutation',
+        'view.orbit': 'mutation',
+        'view.pan': 'mutation',
+        'view.dolly': 'mutation',
+        'view.reset': 'mutation',
+        'ui.hide': 'mutation',
+        'ui.restore': 'mutation',
+        'ui.setLeftStripHidden': 'mutation',
+        'ui.openPanel': 'mutation',
+        'ui.closePanel': 'mutation',
+        'ui.setGizmoMode': 'mutation',
+    };
+    for (const [name, kind] of Object.entries(expected)) {
+        const command = byName.get(name);
+        expect(command).toBeDefined();
+        expect(command).toMatchObject({
+            kind,
+            stateDomain: 'session',
+            undoable: 'none',
+        });
+    }
+});

package/dist/agent/contractCoverage.test.d.ts

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

package/dist/agent/contractCoverage.test.d.ts.map

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

package/dist/agent/contractCoverage.test.js

@@ -0,0 +1,87 @@
+/**
+ * 契约覆盖测试(2026-10-19,Task 16,spec §9):
+ * registerAllAgentCommands 的注册面与 EXPECTED_AGENT_COMMANDS 完全一致
+ * ——缺少与多出都失败,失败输出点名具体命令,不许通过删预期命令变绿。
+ *
+ * 元数据完备性(与命令注册同一份 describe() 快照):
+ * - 每个命令:非空 input/output schema;
+ * - 每个项目 mutation(stateDomain:project 且 kind:mutation):completion、
+ *   非空 errorCodes,且 acceptsExpectedRevision 为 true(spec 8.7);
+ * - 每个 job(kind:job):cancelable、completion、非空 jobResultSchema。
+ *
+ * 注册路径不触达 runtime(命令闭包到 execute 才用),用空对象占位即可。
+ */
+import { AgentCommandRegistry } from './registry';
+import { registerAllAgentCommands } from './registerCommands';
+import { EXPECTED_AGENT_COMMANDS } from './expectedCommands';
+function describeAll() {
+    const registry = new AgentCommandRegistry();
+    registerAllAgentCommands(registry, {});
+    return registry.describe();
+}
+test('命令清单与 spec §9 完全一致:缺少与多出都失败', () => {
+    const actual = describeAll().commands.map((command) => command.name);
+    const expected = [...EXPECTED_AGENT_COMMANDS].sort();
+    const missing = expected.filter((name) => !actual.includes(name));
+    const extra = actual.filter((name) => !expected.includes(name));
+    // 先给点名清单(缺口定位),再给全量比对(顺序即 describe() 排序)
+    expect({ missing, extra }).toEqual({ missing: [], extra: [] });
+    expect(actual).toEqual(expected);
+    expect(new Set(actual).size).toBe(actual.length);
+});
+test('每个命令都有非空 input/output schema', () => {
+    const problems = [];
+    for (const command of describeAll().commands) {
+        if (!command.inputSchema ||
+            typeof command.inputSchema !== 'object' ||
+            Object.keys(command.inputSchema).length === 0) {
+            problems.push(`${command.name}: inputSchema 为空`);
+        }
+        if (!command.outputSchema ||
+            typeof command.outputSchema !== 'object' ||
+            Object.keys(command.outputSchema).length === 0) {
+            problems.push(`${command.name}: outputSchema 为空`);
+        }
+    }
+    expect(problems).toEqual([]);
+});
+test('项目 mutation 元数据完备:undoable/completion/errorCodes/acceptsExpectedRevision', () => {
+    const problems = [];
+    for (const command of describeAll().commands) {
+        if (command.kind !== 'mutation' || command.stateDomain !== 'project') {
+            continue;
+        }
+        if (command.undoable !== 'single-step' && command.undoable !== 'none') {
+            problems.push(`${command.name}: undoable 未声明`);
+        }
+        if (!command.completion) {
+            problems.push(`${command.name}: 项目 mutation 缺 completion`);
+        }
+        if (!command.errorCodes || command.errorCodes.length === 0) {
+            problems.push(`${command.name}: 项目 mutation 缺 errorCodes`);
+        }
+        if (command.acceptsExpectedRevision !== true) {
+            problems.push(`${command.name}: 项目 mutation 应接受 expectedRevision`);
+        }
+    }
+    expect(problems).toEqual([]);
+});
+test('job 元数据完备:cancelable/completion/jobResultSchema', () => {
+    const problems = [];
+    for (const command of describeAll().commands) {
+        if (command.kind !== 'job')
+            continue;
+        if (typeof command.cancelable !== 'boolean') {
+            problems.push(`${command.name}: job 缺 cancelable 声明`);
+        }
+        if (!command.completion) {
+            problems.push(`${command.name}: job 缺 completion`);
+        }
+        if (!command.jobResultSchema ||
+            typeof command.jobResultSchema !== 'object' ||
+            Object.keys(command.jobResultSchema).length === 0) {
+            problems.push(`${command.name}: job 缺非空 jobResultSchema`);
+        }
+    }
+    expect(problems).toEqual([]);
+});