@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,402 @@
+/**
+ * exports.startVideo(2026-10-17,Task 13):视频导出任务命令。
+ *
+ * 布景:真实 core project/sheet + 真实 exportRuntime 控制器(假 React
+ * 会话态 getter/setter),startShotExport 走 doMock 晚绑定假实现
+ * (jest-esbuild 不提升 jest.mock);node 环境。
+ *
+ * 契约要点:
+ *  - job/session、undoable:none、cancelable:true、completion:loaded;
+ *  - 返回 {jobId};handle.done 是任务成功的唯一权威(句柄返回 ≠ 成功);
+ *  - 进度随 sequence position 更新;done resolve 后结果为 BlobCollectSink
+ *    收集的 VideoExportResult{blob,fileName,mimeType,size};
+ *  - jobs.cancel → handle.abort + sink.abort,任务置 cancelled(终态不被
+ *    迟到的 settle 覆盖)并恢复 ShotView;
+ *  - 无活动相机/正在导出 → INVALID_STATE;MediaRecorder 不可用(句柄
+ *    返回 undefined)→ 任务 failed/CAPABILITY_UNAVAILABLE;
+ *  - cameraId 类型不符 → INVALID_ID_KIND;相机不存在 → OBJECT_NOT_FOUND;
+ *  - 控制器未注册 → SCENE_UNAVAILABLE;场景 dispose → 先 abort、恢复视图、
+ *    拒绝未完成任务(API_DISPOSED);
+ *  - jobResultSchema 描述 HTTP FileDescriptor(fileId),JS 结果是 Blob,
+ *    不做 JSON 序列化。
+ */
+import { getProject, val } from '@dreamerbird/core';
+import { AgentApiError } from '../errors';
+/** 晚绑定:doMock 工厂只登记一次,各用例在 setup 里换实现 */
+let activeStartShotExport;
+jest.doMock('../../videoExport/exporter', () => ({
+    __esModule: true,
+    startShotExport: (...args) => activeStartShotExport(...args),
+}));
+let recording;
+/** 假 startShotExport:返回可控 {done,abort,finishEarly};abort 对齐真实行为(sink.abort + done resolve) */
+function stubExporterAvailable() {
+    activeStartShotExport = jest.fn((args) => {
+        const { sink } = args;
+        let resolveDone;
+        let rejectDone;
+        const done = new Promise((res, rej) => {
+            resolveDone = res;
+            rejectDone = rej;
+        });
+        const handle = {
+            done,
+            abort: jest.fn(() => {
+                void sink.abort();
+                resolveDone();
+            }),
+            finishEarly: jest.fn(),
+        };
+        recording = {
+            args: args,
+            handle,
+            resolveDone,
+            rejectDone,
+            recordChunks: async (chunks) => {
+                await sink.start({
+                    mimeType: 'video/webm',
+                    suggestedName: '镜头-test.webm',
+                });
+                for (const chunk of chunks)
+                    await sink.write(chunk);
+                await sink.finish();
+            },
+        };
+        return handle;
+    });
+    return activeStartShotExport;
+}
+/** 编码器不可用:真实 startShotExport 此时返回 undefined 并经 onError 提示 */
+function stubExporterUnavailable() {
+    activeStartShotExport = jest.fn((args) => {
+        args.onError?.('当前浏览器不支持视频录制(MediaRecorder 无可用格式)');
+        return undefined;
+    });
+    return activeStartShotExport;
+}
+const cleanups = [];
+afterEach(() => {
+    while (cleanups.length)
+        cleanups.pop()();
+    activeStartShotExport = undefined;
+    recording = undefined;
+});
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+let projectSeq = 0;
+function loadModules() {
+    return {
+        AgentCommandRegistry: require('../registry').AgentCommandRegistry,
+        createAgentRuntime: require('../runtime').createAgentRuntime,
+        registerExportCommands: require('./exports').registerExportCommands,
+        registerJobCommands: require('./jobs').registerJobCommands,
+        createSceneExportController: require('../runtime/exportRuntime')
+            .createSceneExportController,
+        registerSceneExportController: require('../runtime/exportRuntime')
+            .registerSceneExportController,
+    };
+}
+function makeScene({ withController = true } = {}) {
+    const m = loadModules();
+    const project = getProject(`agent-exports-${++projectSeq}`);
+    const sheet = project.sheet('Scene');
+    const runtime = m.createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => undefined,
+        subscribeHistoric: () => () => { },
+    });
+    const registry = new m.AgentCommandRegistry();
+    m.registerExportCommands(registry, runtime);
+    m.registerJobCommands(registry, runtime);
+    const scene = {
+        cameras: ['Cam 1', 'Cam 2'],
+        activeCameraKey: 'Cam 1',
+        shotView: false,
+        exporting: false,
+        handle: null,
+        lockedCamera: null,
+        canvas: {},
+    };
+    const controller = m.createSceneExportController({
+        sheet,
+        getActiveCameraKey: () => scene.activeCameraKey,
+        hasCamera: (key) => scene.cameras.includes(key),
+        setActiveCamera: (key) => {
+            scene.activeCameraKey = key;
+        },
+        isExporting: () => scene.exporting,
+        getShotView: () => scene.shotView,
+        setShotView: (on) => {
+            scene.shotView = on;
+        },
+        // 页面上只有一个 canvas(快照编辑器的在 shadow DOM 里)
+        getCanvas: () => scene.canvas,
+        setExporting: (on) => {
+            scene.exporting = on;
+        },
+        setActiveHandle: (handle) => {
+            scene.handle = handle;
+        },
+        lockExportCamera: (key) => {
+            scene.lockedCamera = key;
+        },
+    });
+    if (withController) {
+        cleanups.push(m.registerSceneExportController(controller));
+    }
+    cleanups.push(() => controller.dispose(), () => runtime.dispose());
+    return { registry, runtime, controller, scene, sheet };
+}
+/** 轮询任务到终态(job manager 的 done 不经命令暴露,测试读快照) */
+async function settleJob(runtime, jobId) {
+    for (let i = 0; i < 50; i++) {
+        const snapshot = runtime.jobs.get(jobId);
+        if (['succeeded', 'failed', 'cancelled'].includes(snapshot.state)) {
+            return snapshot;
+        }
+        await tick();
+    }
+    return runtime.jobs.get(jobId);
+}
+async function startVideo(registry, args = {}) {
+    return (await registry.execute('exports.startVideo', args, ctx()));
+}
+// ── 注册与元数据 ───────────────────────────────────────────────
+test('exports.startVideo 元数据:job/session、undoable:none、cancelable、completion:loaded', () => {
+    const { registry } = makeScene();
+    expect(registry.has('exports.startVideo')).toBe(true);
+    const described = new Map(registry.describe().commands.map((c) => [c.name, c]));
+    const command = described.get('exports.startVideo');
+    expect(command).toMatchObject({
+        kind: 'job',
+        stateDomain: 'session',
+        undoable: 'none',
+        completion: 'loaded',
+        cancelable: true,
+        acceptsExpectedRevision: false,
+    });
+    // 二进制契约:jobResultSchema 描述 HTTP FileDescriptor;JS 结果是 Blob,不 JSON 序列化
+    expect(command.jobResultSchema.required).toEqual(expect.arrayContaining(['fileId', 'fileName', 'mimeType', 'size']));
+});
+// ── 成功路径 ───────────────────────────────────────────────────
+test('导出成功:返回 jobId,done 是唯一权威,结果为 BlobCollectSink 收集的文件,视角恢复', async () => {
+    const { registry, runtime, controller, scene } = makeScene();
+    const startShotExport = stubExporterAvailable();
+    const { jobId } = await startVideo(registry);
+    expect(runtime.jobs.get(jobId)).toMatchObject({
+        kind: 'exports.startVideo',
+        state: 'running',
+        progress: 0,
+        phase: 'accepted',
+        cancelable: true,
+    });
+    // 视角未生效前不开录;已请求切到镜头视角
+    expect(startShotExport).not.toHaveBeenCalled();
+    expect(scene.shotView).toBe(true);
+    // 模拟 React 副作用:ShotView 生效,开录
+    controller.notifySceneReady();
+    expect(startShotExport).toHaveBeenCalledTimes(1);
+    expect(scene.exporting).toBe(true);
+    expect(scene.lockedCamera).toBe('Cam 1');
+    // handle.done 是任务成功的唯一权威:句柄已返回 ≠ 成功
+    expect(runtime.jobs.get(jobId).state).toBe('running');
+    await recording.recordChunks([
+        new Uint8Array([1, 2, 3]),
+        new Uint8Array([4, 5]),
+    ]);
+    recording.resolveDone();
+    const snapshot = await settleJob(runtime, jobId);
+    expect(snapshot.state).toBe('succeeded');
+    expect(snapshot.phase).toBe('loaded');
+    expect(snapshot.progress).toBe(1);
+    const result = snapshot.result;
+    expect(result.fileName).toBe('镜头-test.webm');
+    expect(result.mimeType).toBe('video/webm');
+    expect(result.size).toBe(5);
+    expect([...new Uint8Array(await result.blob.arrayBuffer())]).toEqual([
+        1, 2, 3, 4, 5,
+    ]);
+    // 收尾:恢复导出前视角、清导出态与句柄
+    expect(scene.shotView).toBe(false);
+    expect(scene.exporting).toBe(false);
+    expect(scene.handle).toBe(null);
+    expect(scene.lockedCamera).toBe(null);
+});
+test('进度随 sequence position 更新', async () => {
+    const { registry, runtime, controller, sheet } = makeScene();
+    stubExporterAvailable();
+    const { jobId } = await startVideo(registry);
+    controller.notifySceneReady();
+    const length = val(sheet.sequence.pointer.length);
+    sheet.sequence.position = length / 2;
+    await tick();
+    expect(runtime.jobs.get(jobId).progress).toBeCloseTo(0.5);
+    expect(runtime.jobs.get(jobId).state).toBe('running');
+    await recording.recordChunks([new Uint8Array([1])]);
+    recording.resolveDone();
+    const snapshot = await settleJob(runtime, jobId);
+    expect(snapshot.state).toBe('succeeded');
+});
+test('指定 cameraId:先激活该相机再开录', async () => {
+    const { registry, runtime, controller, scene } = makeScene();
+    stubExporterAvailable();
+    const { jobId } = await startVideo(registry, { cameraId: 'camera:Cam 2' });
+    expect(scene.activeCameraKey).toBe('Cam 2');
+    controller.notifySceneReady();
+    expect(scene.lockedCamera).toBe('Cam 2');
+    await recording.recordChunks([new Uint8Array([1])]);
+    recording.resolveDone();
+    expect((await settleJob(runtime, jobId)).state).toBe('succeeded');
+});
+test('shotView 已开启且相机无需切换:立即开录,完成后保持镜头视角', async () => {
+    const { registry, runtime, scene } = makeScene();
+    const startShotExport = stubExporterAvailable();
+    scene.shotView = true;
+    const { jobId } = await startVideo(registry);
+    expect(startShotExport).toHaveBeenCalledTimes(1);
+    await recording.recordChunks([new Uint8Array([1])]);
+    recording.resolveDone();
+    expect((await settleJob(runtime, jobId)).state).toBe('succeeded');
+    // 导出前就在镜头视角:恢复到 true(不退出)
+    expect(scene.shotView).toBe(true);
+});
+// ── 取消 ───────────────────────────────────────────────────────
+test('jobs.cancel:handle.abort + sink.abort,任务置 cancelled 且不被迟到 settle 覆盖,视角恢复', async () => {
+    const { registry, runtime, controller, scene } = makeScene();
+    stubExporterAvailable();
+    const { jobId } = await startVideo(registry);
+    controller.notifySceneReady();
+    await recording.recordChunks([new Uint8Array([1, 2])]);
+    const cancelled = (await registry.execute('jobs.cancel', { jobId }, ctx()));
+    expect(cancelled.state).toBe('cancelled');
+    expect(recording.handle.abort).toHaveBeenCalledTimes(1);
+    // sink 已 abort:blob() 抛 INVALID_STATE
+    const sink = recording.args.sink;
+    expect(() => sink.blob()).toThrow();
+    // abort 后 done resolve 是迟到的 settle:终态 cancelled 不被覆盖
+    const snapshot = await settleJob(runtime, jobId);
+    expect(snapshot.state).toBe('cancelled');
+    expect(scene.shotView).toBe(false);
+    expect(scene.exporting).toBe(false);
+});
+test('用户侧中止(Esc/开录相机被删,signal 未 abort):任务置 cancelled 并带 JOB_CANCELLED,非 failed/INVALID_STATE', async () => {
+    const { registry, runtime, controller, scene } = makeScene();
+    stubExporterAvailable();
+    const { jobId } = await startVideo(registry);
+    controller.notifySceneReady();
+    await recording.recordChunks([new Uint8Array([1, 2])]);
+    // 模拟 Esc/相机删除:场景直调 handle.abort(signal 不经过 jobs.cancel);
+    // 假实现对齐真实 exporter:abort 丢弃内容(sink.abort)后 done resolve
+    recording.handle.abort();
+    const snapshot = await settleJob(runtime, jobId);
+    // 轮询任务的 Agent 必须能区分"被用户中止"与真失败
+    expect(snapshot.state).toBe('cancelled');
+    expect(snapshot.error.code).toBe('JOB_CANCELLED');
+    expect(scene.shotView).toBe(false);
+    expect(scene.exporting).toBe(false);
+});
+// ── 前置校验失败(任务启动前拒绝命令) ──────────────────────────
+test('无活动相机 → INVALID_STATE,不起任务', async () => {
+    const { registry, scene } = makeScene();
+    stubExporterAvailable();
+    scene.cameras = [];
+    scene.activeCameraKey = null;
+    await expect(startVideo(registry)).rejects.toMatchObject({
+        code: 'INVALID_STATE',
+    });
+    expect(activeStartShotExport).not.toHaveBeenCalled();
+});
+test('已有导出进行中 → INVALID_STATE', async () => {
+    const { registry, runtime, controller } = makeScene();
+    stubExporterAvailable();
+    const { jobId } = await startVideo(registry);
+    controller.notifySceneReady();
+    await expect(startVideo(registry)).rejects.toMatchObject({
+        code: 'INVALID_STATE',
+    });
+    await recording.recordChunks([new Uint8Array([1])]);
+    recording.resolveDone();
+    expect((await settleJob(runtime, jobId)).state).toBe('succeeded');
+});
+test('cameraId 类型不符 → INVALID_ID_KIND;相机不存在 → OBJECT_NOT_FOUND', async () => {
+    const { registry } = makeScene();
+    stubExporterAvailable();
+    await expect(startVideo(registry, { cameraId: 'model:Y Bot' })).rejects.toMatchObject({ code: 'INVALID_ID_KIND' });
+    await expect(startVideo(registry, { cameraId: 'camera:Nope' })).rejects.toMatchObject({ code: 'OBJECT_NOT_FOUND' });
+    expect(activeStartShotExport).not.toHaveBeenCalled();
+});
+test('cameraId 非法参数 → INVALID_ARGUMENT', async () => {
+    const { registry } = makeScene();
+    await expect(startVideo(registry, { cameraId: 123 })).rejects.toMatchObject({
+        code: 'INVALID_ARGUMENT',
+    });
+    await expect(startVideo(registry, { cameraId: '' })).rejects.toMatchObject({
+        code: 'INVALID_ARGUMENT',
+    });
+});
+test('导出控制器未注册 → SCENE_UNAVAILABLE', async () => {
+    const { registry } = makeScene({ withController: false });
+    await expect(startVideo(registry)).rejects.toMatchObject({
+        code: 'SCENE_UNAVAILABLE',
+    });
+});
+// ── 运行期失败与场景卸载 ───────────────────────────────────────
+test('MediaRecorder 不可用(句柄 undefined)→ 任务 failed/CAPABILITY_UNAVAILABLE,视角恢复', async () => {
+    const { registry, runtime, controller, scene } = makeScene();
+    stubExporterUnavailable();
+    const { jobId } = await startVideo(registry);
+    controller.notifySceneReady();
+    const snapshot = await settleJob(runtime, jobId);
+    expect(snapshot.state).toBe('failed');
+    expect(snapshot.error.code).toBe('CAPABILITY_UNAVAILABLE');
+    expect(scene.shotView).toBe(false);
+    expect(scene.exporting).toBe(false);
+});
+test('录制中途失败 → 任务 failed,视角恢复', async () => {
+    const { registry, runtime, controller, scene } = makeScene();
+    stubExporterAvailable();
+    const { jobId } = await startVideo(registry);
+    controller.notifySceneReady();
+    recording.rejectDone(new Error('编码器炸了'));
+    const snapshot = await settleJob(runtime, jobId);
+    expect(snapshot.state).toBe('failed');
+    expect(snapshot.error.message).toContain('编码器炸了');
+    expect(scene.shotView).toBe(false);
+    expect(scene.exporting).toBe(false);
+});
+test('录制中途的结构化失败保留原错误码(INVALID_STATE 不被误归为取消)', async () => {
+    const { registry, runtime, controller } = makeScene();
+    stubExporterAvailable();
+    const { jobId } = await startVideo(registry);
+    controller.notifySceneReady();
+    // 真实路径示例:sink.write 拒绝(写盘失败)经 exporter 收尾后 done 拒绝
+    recording.rejectDone(new AgentApiError('INVALID_STATE', '写入失败'));
+    const snapshot = await settleJob(runtime, jobId);
+    expect(snapshot.state).toBe('failed');
+    expect(snapshot.error.code).toBe('INVALID_STATE');
+});
+test('场景 dispose:先 abort 在录任务,再恢复视图,最后拒绝未完成任务(API_DISPOSED)', async () => {
+    const { registry, runtime, controller, scene } = makeScene();
+    stubExporterAvailable();
+    const { jobId } = await startVideo(registry);
+    controller.notifySceneReady();
+    expect(scene.exporting).toBe(true);
+    controller.dispose();
+    expect(recording.handle.abort).toHaveBeenCalledTimes(1);
+    expect(scene.shotView).toBe(false);
+    const snapshot = await settleJob(runtime, jobId);
+    expect(snapshot.state).toBe('failed');
+    expect(snapshot.error.code).toBe('API_DISPOSED');
+});
+test('会话销毁后 exports.startVideo 返回 API_DISPOSED', async () => {
+    const { registry, runtime } = makeScene();
+    runtime.dispose();
+    await expect(startVideo(registry)).rejects.toMatchObject({
+        code: 'API_DISPOSED',
+    });
+});

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

@@ -0,0 +1,17 @@
+import type { AgentCommandRegistry } from '../registry';
+import type { AgentRuntime } from '../runtime';
+/** 历史门面(Task 15 由同名命令转发实现) */
+export type HistoryApi = {
+    undo(args?: {
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    redo(args?: {
+        expectedRevision?: number;
+    }): Promise<{
+        revision: number;
+    }>;
+};
+export declare function registerHistoryCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=history.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../src/agent/commands/history.ts"],"names":[],"mappings":"AAYA,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,IAAI,CAAC,IAAI,CAAC,EAAE;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACrE,IAAI,CAAC,IAAI,CAAC,EAAE;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAC,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CACtE,CAAA;AA0CD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAoDN"}

package/dist/agent/commands/history.js

@@ -0,0 +1,96 @@
+/**
+ * history 命令(2026-10-17,Task 6):undo/redo。
+ *
+ * 直接调用 Studio 真实 undo()/redo();revision 等一个 core tick 再读
+ * (F2 修复:historic 指针通知经 prism.onChange 排到 ticker 下一 tick,
+ * undo/redo 后同步读拿到的是操作前的值),绝不伪造 canUndo/canRedo,
+ * 也不把它们塞进结果。
+ * 历史恢复的是项目状态,但 undo 本身不再产生可撤销步骤:undoable:none。
+ * 写命令的 expectedRevision 乐观并发对 undo/redo 一致生效:revision 匹配
+ * 检查先于 Studio 调用,冲突时不产生任何副作用。
+ */
+import { AgentApiError } from '../errors';
+import { requireFiniteNumber, requireObject } from '../validation';
+const historyInput = {
+    type: 'object',
+    properties: {
+        expectedRevision: {
+            type: 'number',
+            description: '乐观并发:读取场景时的 revision',
+        },
+    },
+    additionalProperties: false,
+};
+const revisionOutput = {
+    type: 'object',
+    properties: { revision: { type: 'number' } },
+    required: ['revision'],
+};
+/** 无参/可选 expectedRevision 命令的运行时校验:允许省略参数或空对象 */
+function validateHistoryArgs(value) {
+    const args = value === undefined || value === null ? {} : requireObject(value);
+    let expectedRevision;
+    if (args.expectedRevision !== undefined) {
+        expectedRevision = requireFiniteNumber(args.expectedRevision, 'expectedRevision');
+    }
+    return { expectedRevision };
+}
+function requireStudio(runtime) {
+    const studio = runtime.getStudio();
+    if (!studio) {
+        throw new AgentApiError('SCENE_UNAVAILABLE', 'Studio 不可用');
+    }
+    return studio;
+}
+export function registerHistoryCommands(registry, runtime) {
+    registry.register({
+        name: 'history.undo',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'none',
+        completion: 'committed',
+        inputSchema: historyInput,
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: validateHistoryArgs,
+        execute: async (args) => {
+            runtime.assertActive();
+            // 乐观并发先于 Studio 调用;冲突时不产生任何副作用
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            requireStudio(runtime).undo();
+            // historic 通知 tick 调度:等一个 tick,返回 undo 后的真实 revision
+            return { revision: await runtime.nextRevision() };
+        },
+    });
+    registry.register({
+        name: 'history.redo',
+        kind: 'mutation',
+        stateDomain: 'project',
+        undoable: 'none',
+        completion: 'committed',
+        inputSchema: historyInput,
+        outputSchema: revisionOutput,
+        errorCodes: [
+            'API_DISPOSED',
+            'INVALID_ARGUMENT',
+            'REVISION_CONFLICT',
+            'SCENE_UNAVAILABLE',
+        ],
+        validate: validateHistoryArgs,
+        execute: async (args) => {
+            runtime.assertActive();
+            if (args.expectedRevision !== undefined) {
+                runtime.assertRevision(args.expectedRevision);
+            }
+            requireStudio(runtime).redo();
+            return { revision: await runtime.nextRevision() };
+        },
+    });
+}

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

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

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

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

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

@@ -0,0 +1,140 @@
+let projectSeq = 0;
+const cleanups = [];
+afterEach(() => {
+    while (cleanups.length)
+        cleanups.pop()();
+});
+const ctx = () => ({
+    requestId: 'test',
+    signal: new AbortController().signal,
+});
+function setup() {
+    const core = require('@dreamerbird/core');
+    const { globals } = require('@dreamerbird/core/globals');
+    const { AgentCommandRegistry } = require('../registry');
+    const { createAgentRuntime } = require('../runtime');
+    const { registerHistoryCommands } = require('./history');
+    const project = core.getProject(`agent-history-${++projectSeq}`, {
+        state: {
+            definitionVersion: globals.currentProjectStateDefinitionVersion,
+            sheetsById: {},
+        },
+    });
+    const sheet = project.sheet('Scene');
+    let notifyHistoric = () => { };
+    // undo/redo 内同步触发 historic 通知:与生产通知时序一致
+    const undoRedoStudio = {
+        undo: jest.fn(() => notifyHistoric()),
+        redo: jest.fn(() => notifyHistoric()),
+    };
+    let studioAvailable = true;
+    const runtime = createAgentRuntime({
+        project,
+        sheet,
+        library: {},
+        getStudio: () => (studioAvailable ? undoRedoStudio : undefined),
+        subscribeHistoric: (listener) => {
+            notifyHistoric = listener;
+            return () => { };
+        },
+    });
+    const registry = new AgentCommandRegistry();
+    registerHistoryCommands(registry, runtime);
+    return {
+        registry,
+        runtime,
+        undoRedoStudio,
+        setStudioAvailable: (available) => {
+            studioAvailable = available;
+        },
+    };
+}
+describe('history.undo', () => {
+    test('调用 studio.undo 并返回当前 revision', async () => {
+        const { registry, undoRedoStudio } = setup();
+        const result = await registry.execute('history.undo', {}, ctx());
+        expect(undoRedoStudio.undo).toHaveBeenCalledTimes(1);
+        expect(undoRedoStudio.redo).not.toHaveBeenCalled();
+        // 通知同步递增后返回实时 revision(1 → 2),不手工加一也不伪造
+        expect(result).toEqual({ revision: 2 });
+    });
+});
+describe('history.redo', () => {
+    test('调用 studio.redo 并返回当前 revision', async () => {
+        const { registry, undoRedoStudio } = setup();
+        const result = await registry.execute('history.redo', {}, ctx());
+        expect(undoRedoStudio.redo).toHaveBeenCalledTimes(1);
+        expect(undoRedoStudio.undo).not.toHaveBeenCalled();
+        expect(result).toEqual({ revision: 2 });
+    });
+});
+describe('history 可用性', () => {
+    test('结果不携带 canUndo/canRedo', async () => {
+        const { registry } = setup();
+        const undoResult = await registry.execute('history.undo', {}, ctx());
+        const redoResult = await registry.execute('history.redo', {}, ctx());
+        expect(Object.keys(undoResult)).toEqual(['revision']);
+        expect(Object.keys(redoResult)).toEqual(['revision']);
+    });
+    test('expectedRevision 匹配时正常执行并返回当前 revision', async () => {
+        const { registry, undoRedoStudio } = setup();
+        const undoResult = await registry.execute('history.undo', { expectedRevision: 1 }, ctx());
+        const redoResult = await registry.execute('history.redo', { expectedRevision: 2 }, ctx());
+        expect(undoRedoStudio.undo).toHaveBeenCalledTimes(1);
+        expect(undoRedoStudio.redo).toHaveBeenCalledTimes(1);
+        expect(undoResult).toEqual({ revision: 2 });
+        expect(redoResult).toEqual({ revision: 3 });
+    });
+    test('expectedRevision 冲突返回 REVISION_CONFLICT 且不调用 Studio', async () => {
+        const { registry, undoRedoStudio } = setup();
+        await expect(registry.execute('history.undo', { expectedRevision: 99 }, ctx())).rejects.toMatchObject({ code: 'REVISION_CONFLICT' });
+        await expect(registry.execute('history.redo', { expectedRevision: 99 }, ctx())).rejects.toMatchObject({ code: 'REVISION_CONFLICT' });
+        expect(undoRedoStudio.undo).not.toHaveBeenCalled();
+        expect(undoRedoStudio.redo).not.toHaveBeenCalled();
+    });
+    test('expectedRevision 非有限数返回 INVALID_ARGUMENT', async () => {
+        const { registry, undoRedoStudio } = setup();
+        for (const bad of [NaN, Infinity, '1']) {
+            await expect(registry.execute('history.undo', { expectedRevision: bad }, ctx())).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+        }
+        expect(undoRedoStudio.undo).not.toHaveBeenCalled();
+    });
+    test('describe 元数据声明接受 expectedRevision 且真实生效', () => {
+        const { registry } = setup();
+        for (const name of ['history.undo', 'history.redo']) {
+            const described = registry
+                .describe()
+                .commands.find((c) => c.name === name);
+            expect(described).toMatchObject({
+                acceptsExpectedRevision: true,
+            });
+        }
+    });
+    test('Studio 不可用返回 SCENE_UNAVAILABLE', async () => {
+        const { registry, setStudioAvailable } = setup();
+        setStudioAvailable(false);
+        await expect(registry.execute('history.undo', {}, ctx())).rejects.toMatchObject({ code: 'SCENE_UNAVAILABLE' });
+        await expect(registry.execute('history.redo', {}, ctx())).rejects.toMatchObject({ code: 'SCENE_UNAVAILABLE' });
+    });
+    test('dispose 后命令拒绝 API_DISPOSED', async () => {
+        const { registry, runtime } = setup();
+        runtime.dispose();
+        await expect(registry.execute('history.undo', {}, ctx())).rejects.toMatchObject({ code: 'API_DISPOSED' });
+    });
+    test('命令注册且元数据为项目命令', () => {
+        const { registry } = setup();
+        for (const name of ['history.undo', 'history.redo']) {
+            expect(registry.has(name)).toBe(true);
+            const described = registry
+                .describe()
+                .commands.find((c) => c.name === name);
+            expect(described).toMatchObject({
+                kind: 'mutation',
+                stateDomain: 'project',
+                undoable: 'none',
+                completion: 'committed',
+            });
+        }
+    });
+});
+export {};